System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 33dd9cb9d6f75d48042d47f58129707b1872c41f:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
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 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 33 2e 38 2e 31 31 22 0a 23 64       "3.8.11".#d
10b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
10c0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 38  SION_NUMBER 3008
10d0: 30 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  011.#define SQLI
10e0: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20  TE_SOURCE_ID    
10f0: 20 20 22 32 30 31 35 2d 30 37 2d 30 33 20 32 31    "2015-07-03 21
1100: 3a 33 38 3a 30 39 20 62 32 30 32 65 32 61 31 64  :38:09 b202e2a1d
1110: 37 33 64 31 30 34 64 37 39 35 64 32 32 35 32 62  73d104d795d2252b
1120: 31 63 36 66 36 31 64 36 35 62 66 62 32 39 35 22  1c6f61d65bfb295"
1130: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1140: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
1150: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
1160: 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
1170: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c  sqlite3_version,
1180: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
1190: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
11a0: 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65  terfaces provide
11b0: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
11c0: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51  ation as the [SQ
11d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a  LITE_VERSION],.*
11e0: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
11f0: 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b  N_NUMBER], and [
1200: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1210: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1220: 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61   macros.** but a
1230: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  re associated wi
1240: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
1250: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
1260: 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61  ader file.  ^(Ca
1270: 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61  utious.** progra
1280: 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c  mmers might incl
1290: 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61  ude assert() sta
12a0: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72  tements in their
12b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
12c0: 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76  ** verify that v
12d0: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
12e0: 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  y these interfac
12f0: 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63  es match the mac
1300: 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65  ros in.** the he
1310: 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 69  ader, and thus i
1320: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
1330: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a  pplication is.**
1340: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1350: 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20  atching library 
1360: 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73  and header files
1370: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  ..**.** <blockqu
1380: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73  ote><pre>.** ass
1390: 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62  ert( sqlite3_lib
13a0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
13b0: 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ==SQLITE_VERSION
13c0: 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73  _NUMBER );.** as
13d0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
13e0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c  ite3_sourceid(),
13f0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1400: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1410: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1420: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1430: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1440: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1450: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1460: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1470: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1480: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
1490: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
14a0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
14b0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
14c0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14d0: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
14e0: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
14f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1500: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1510: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1520: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1530: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1540: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1550: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
1560: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
1570: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
1580: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
1590: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
15a0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
15b0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
15c0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
15d0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
15e0: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
15f0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1600: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1610: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1620: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  BER].  ^The sqli
1630: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66  te3_sourceid() f
1640: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1650: 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
1660: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61   a string consta
1670: 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69  nt whose value i
1680: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68  s the same as th
1690: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  e .** [SQLITE_SO
16a0: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
16b0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a  ocessor macro..*
16c0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
16d0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
16e0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
16f0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
1700: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1710: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
1720: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
1730: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49  on[];.SQLITE_API
1740: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1750: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1760: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76  te3_libversion(v
1770: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
1780: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1790: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
17a0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69  te3_sourceid(voi
17b0: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
17c0: 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
17d0: 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  L sqlite3_libver
17e0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
17f0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1800: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
1810: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
1820: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1830: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1840: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1850: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1860: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
1870: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
1880: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
1890: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
18a0: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
18b0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
18c0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
18d0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
18e0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
18f0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
1900: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
1910: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
1920: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1930: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1940: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1950: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1960: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
1970: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
1980: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
1990: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
19a0: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
19b0: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
19c0: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
19d0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
19e0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
19f0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
1a00: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1a10: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
1a20: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1a30: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1a40: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1a50: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1a60: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1a70: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1a80: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
1a90: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
1aa0: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
1ab0: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
1ac0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1ad0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
1ae0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1af0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
1b00: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
1b10: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
1b20: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1b30: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1b40: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1b50: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1b60: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1b70: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1b80: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1b90: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1ba0: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1bb0: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1bc0: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1bd0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1be0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1bf0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1c00: 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49  DIAGS.SQLITE_API
1c10: 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1c20: 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ALL sqlite3_comp
1c30: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63  ileoption_used(c
1c40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e  onst char *zOptN
1c50: 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ame);.SQLITE_API
1c60: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1c70: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1c80: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1c90: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1ca0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1cb0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1cc0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1cd0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1ce0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1cf0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1d00: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1d10: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1d20: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1d30: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1d40: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1d50: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1d60: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1d70: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1d80: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1d90: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1da0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1db0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1dc0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1dd0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1de0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1df0: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1e00: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1e10: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1e20: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1e30: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1e40: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1e50: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e60: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1e70: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1e80: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1e90: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1ea0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1eb0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1ec0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1ed0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1ee0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1ef0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1f00: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1f10: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1f20: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1f30: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1f40: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1f50: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1f60: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1f70: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1f80: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1f90: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1fa0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1fb0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1fc0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1fd0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
1fe0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
1ff0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2000: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
2010: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
2020: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
2030: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
2040: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
2050: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
2060: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
2070: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
2080: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
2090: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
20a0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
20b0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
20c0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
20d0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
20e0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
20f0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2100: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2110: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2120: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2130: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2140: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2150: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2160: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
2170: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
2180: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
2190: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
21a0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
21b0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
21c0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
21d0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
21e0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
21f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2200: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2210: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2220: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
2230: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
2240: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
2250: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2260: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2270: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2280: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2290: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
22a0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
22b0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
22c0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
22d0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
22e0: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
22f0: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2300: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
2310: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2320: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
2330: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
2340: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2350: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
2360: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2370: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2380: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2390: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23a0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
23b0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
23c0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
23d0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
23e0: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
23f0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
2400: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
2410: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2420: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
2430: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
2440: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
2450: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
2460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
2470: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
2480: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
2490: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
24a0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
24b0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
24c0: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
24d0: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
24e0: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
24f0: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
2500: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2510: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
2520: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
2530: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
2540: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
2550: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
2560: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
2570: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2580: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20  close_v2()] are 
2590: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e  its destructors.
25a0: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
25b0: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
25c0: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
25d0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25e0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
25f0: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2600: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
2610: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
2620: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
2630: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
2640: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
2650: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
2660: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
2670: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
2680: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
2690: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
26a0: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b  teger Types.** K
26b0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
26c0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
26d0: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
26e0: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
26f0: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
2700: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
2710: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
2720: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
2730: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
2740: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
2750: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
2760: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
2770: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
2780: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
2790: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
27a0: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
27b0: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
27c0: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
27d0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
27e0: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
27f0: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
2800: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
2810: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
2820: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79   sqlite_int64 ty
2840: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
2850: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  teger values.** 
2860: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
2870: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
2880: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
2890: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e  75807 inclusive.
28a0: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
28b0: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  3_uint64 and sql
28c0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
28d0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
28e0: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65  er values .** be
28f0: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34  tween 0 and +184
2900: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31  4674407370955161
2910: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a  5 inclusive..*/.
2920: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
2930: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
2940: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2950: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
2960: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2970: 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54  igned SQLITE_INT
2980: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
2990: 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66  int64;.#elif def
29a0: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c  ined(_MSC_VER) |
29b0: 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c  | defined(__BORL
29c0: 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65  ANDC__).  typede
29d0: 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  f __int64 sqlite
29e0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
29f0: 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74  f unsigned __int
2a00: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2a10: 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65  ;.#else.  typede
2a20: 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  f long long int 
2a30: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
2a40: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
2a50: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
2a60: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2a70: 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c  ndif.typedef sql
2a80: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
2a90: 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66  3_int64;.typedef
2aa0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73   sqlite_uint64 s
2ab0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a  qlite3_uint64;..
2ac0: 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69  /*.** If compili
2ad0: 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73  ng for a process
2ae0: 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c  or that lacks fl
2af0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70  oating point sup
2b00: 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74  port,.** substit
2b10: 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20  ute integer for 
2b20: 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a  floating-point..
2b30: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
2b40: 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50  _OMIT_FLOATING_P
2b50: 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f  OINT.# define do
2b60: 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  uble sqlite3_int
2b70: 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  64.#endif../*.**
2b80: 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69   CAPI3REF: Closi
2b90: 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  ng A Database Co
2ba0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 54  nnection.** DEST
2bb0: 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a  RUCTOR: sqlite3.
2bc0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2bd0: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73  e3_close() and s
2be0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2bf0: 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  ) routines are d
2c00: 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f  estructors.** fo
2c10: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  r the [sqlite3] 
2c20: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c  object..** ^Call
2c30: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f  s to sqlite3_clo
2c40: 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  se() and sqlite3
2c50: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75  _close_v2() retu
2c60: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  rn [SQLITE_OK] i
2c70: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  f.** the [sqlite
2c80: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63  3] object is suc
2c90: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f  cessfully destro
2ca0: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f  yed and all asso
2cb0: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72  ciated.** resour
2cc0: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
2cd0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ted..**.** ^If t
2ce0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2cf0: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69  ection is associ
2d00: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61  ated with unfina
2d10: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a  lized prepared.*
2d20: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20  * statements or 
2d30: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
2d40: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74  e3_backup object
2d50: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  s then sqlite3_c
2d60: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c  lose().** will l
2d70: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73  eave the databas
2d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
2d90: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  n and return [SQ
2da0: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e  LITE_BUSY]..** ^
2db0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  If sqlite3_close
2dc0: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
2dd0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2de0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2df0: 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75  ents.** and/or u
2e00: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
2e10: 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20  3_backups, then 
2e20: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2e30: 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a  nection becomes.
2e40: 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22  ** an unusable "
2e50: 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69  zombie" which wi
2e60: 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
2e70: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
2e80: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74  when the.** last
2e90: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ea0: 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2eb0: 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c   or the last sql
2ec0: 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a  ite3_backup is.*
2ed0: 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65  * finished.  The
2ee0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2ef0: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
2f00: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
2f10: 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c  e with.** host l
2f20: 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72  anguages that ar
2f30: 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63  e garbage collec
2f40: 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74  ted, and where t
2f50: 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63  he order in whic
2f60: 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73  h.** destructors
2f70: 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61   are called is a
2f80: 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  rbitrary..**.** 
2f90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
2fa0: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  uld [sqlite3_fin
2fb0: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2fc0: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20  ] all [prepared 
2fd0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20  statements],.** 
2fe0: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
2ff0: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c  ose | close] all
3000: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
3010: 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
3020: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20  3_backup_finish 
3030: 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73  | finish] all [s
3040: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3050: 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65  bjects associate
3060: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73  d.** with the [s
3070: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
3080: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69  rior to attempti
3090: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
30a0: 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20  object.  ^If.** 
30b0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
30c0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  () is called on 
30d0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
30e0: 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69  ection] that sti
30f0: 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61  ll has.** outsta
3100: 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20  nding [prepared 
3110: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c  statements], [BL
3120: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3130: 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  /or.** [sqlite3_
3140: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3150: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20  then it returns 
3160: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20  [SQLITE_OK] and 
3170: 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e  the deallocation
3180: 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73  .** of resources
3190: 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e 74   is deferred unt
31a0: 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64  il all [prepared
31b0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42   statements], [B
31c0: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a  LOB handles],.**
31d0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61   and [sqlite3_ba
31e0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72  ckup] objects ar
31f0: 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64  e also destroyed
3200: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b  ..**.** ^If an [
3210: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
3220: 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68 69  is destroyed whi
3230: 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  le a transaction
3240: 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65   is open,.** the
3250: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3260: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
3270: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
3280: 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72   The C parameter
3290: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
32a0: 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69  se(C)] and [sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d  te3_close_v2(C)]
32c0: 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
32d0: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
32e0: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
32f0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
3300: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
3310: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
3320: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
3330: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
3340: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
3350: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
3360: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
3370: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
3380: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20  ite3_close() or 
3390: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
33a0: 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  () with a NULL p
33b0: 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65  ointer.** argume
33c0: 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  nt is a harmless
33d0: 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54   no-op..*/.SQLIT
33e0: 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
33f0: 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
3400: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29  _close(sqlite3*)
3410: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
3420: 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3440: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3450: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3460: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
3470: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
3480: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
3490: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
34a0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
34b0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
34c0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
34d0: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
34e0: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
34f0: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
3500: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
3510: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
3520: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
3530: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
3540: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3550: 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
3560: 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
3570: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3580: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
3590: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
35a0: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
35b0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
35c0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
35d0: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
35e0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20  finalize()],.** 
35f0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
3600: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75  pplication to ru
3610: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65  n multiple state
3620: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20  ments of SQL.** 
3630: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
3640: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43  o use a lot of C
3650: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54   code. .**.** ^T
3660: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3670: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73  ) interface runs
3680: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54   zero or more UT
3690: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20  F-8 encoded,.** 
36a0: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
36b0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
36c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74  s passed into it
36d0: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a  s 2nd argument,.
36e0: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ** in the contex
36f0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
3700: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
3710: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20  assed in as its 
3720: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  1st.** argument.
3730: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
3740: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74  ck function of t
3750: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3760: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
3770: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
3780: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76  , then it is inv
3790: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65  oked for each re
37a0: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69  sult row.** comi
37b0: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76  ng out of the ev
37c0: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74  aluated SQL stat
37d0: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74  ements.  ^The 4t
37e0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  h argument to.**
37f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3800: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75  is relayed throu
3810: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72  gh to the 1st ar
3820: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a  gument of each.*
3830: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63  * callback invoc
3840: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20  ation.  ^If the 
3850: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72  callback pointer
3860: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3870: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  ().** is NULL, t
3880: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20  hen no callback 
3890: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20  is ever invoked 
38a0: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20  and result rows 
38b0: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a  are.** ignored..
38c0: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  **.** ^If an err
38d0: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
38e0: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53  evaluating the S
38f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
3900: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  ssed into.** sql
3910: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65  ite3_exec(), the
3920: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  n execution of t
3930: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
3940: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a  ment stops and.*
3950: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61  * subsequent sta
3960: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70  tements are skip
3970: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74  ped.  ^If the 5t
3980: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3990: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
39a0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
39b0: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  n any error mess
39c0: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
39d0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
39e0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
39f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
3a00: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  nd passed back t
3a10: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3a20: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20  arameter..** To 
3a30: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61  avoid memory lea
3a40: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ks, the applicat
3a50: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b  ion should invok
3a60: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
3a70: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d  )].** on error m
3a80: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72  essage strings r
3a90: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
3aa0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3ab0: 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  r of.** of sqlit
3ac0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
3ad0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
3ae0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
3af0: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3b00: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3b10: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3b20: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3b30: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
3b40: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
3b50: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3b60: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
3b70: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
3b80: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
3b90: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
3ba0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
3bb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3bc0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3bd0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
3be0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3bf0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
3c00: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
3c10: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
3c20: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
3c30: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
3c40: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
3c50: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
3c60: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
3c70: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
3c80: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3c90: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
3ca0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
3cb0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
3cc0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
3cd0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
3ce0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3cf0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
3d00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3d10: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3d20: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
3d30: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
3d40: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
3d50: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
3d60: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
3d70: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
3d80: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
3d90: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
3da0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
3db0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
3dc0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
3dd0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3de0: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
3df0: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
3e00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3e20: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3e30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
3e50: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
3e60: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
3e70: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
3e80: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
3e90: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
3ea0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3eb0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
3ec0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
3ed0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3ee0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3ef0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3f00: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
3f10: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
3f20: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
3f30: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
3f40: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
3f50: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
3f60: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
3f70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3f80: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3f90: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
3fa0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
3fb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
3fc0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
3fd0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3fe0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e  lication must in
3ff0: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
4000: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
4010: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
4020: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
4030: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
4040: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
4050: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
4060: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
4070: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74  t close the [dat
4080: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4090: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
40a0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
40b0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
40c0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
40d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
40e0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
40f0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4100: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
4110: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
4120: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
4130: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
4140: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
4150: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
4160: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
4170: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
4180: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
4190: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
41a0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
41b0: 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71  lite3_exec(.  sq
41c0: 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20  lite3*,         
41d0: 20 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 2f 2a 20 41 6e 20 6f           /* An o
41f0: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
4200: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71    const char *sq
4210: 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4230: 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
4240: 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63  ted */.  int (*c
4250: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
4260: 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a  nt,char**,char**
4270: 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  ),  /* Callback 
4280: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
4290: 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20  id *,           
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 2f 2a 20 31 73 74 20           /* 1st 
42c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
42d0: 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a  back */.  char *
42e0: 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20  *errmsg         
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4300: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
4310: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
4320: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
4330: 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64  3REF: Result Cod
4340: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
4350: 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66  {result code def
4360: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4370: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63  Many SQLite func
4380: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20  tions return an 
4390: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63  integer result c
43a0: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74  ode from the set
43b0: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69   shown.** here i
43c0: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63  n order to indic
43d0: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66  ate success or f
43e0: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
43f0: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
4400: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
4410: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
4420: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
4430: 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64  ee also: [extend
4440: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64  ed result code d
4450: 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23  efinitions].*/.#
4460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
4470: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
4480: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
4490: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
44a0: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
44b0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
44c0: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
44d0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
44e0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
44f0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
4500: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
4510: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
4520: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
4530: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
4540: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
4550: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
4560: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
4570: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
4580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
4590: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
45a0: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
45b0: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
45c0: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
45d0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
45e0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
45f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
4600: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
4610: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
4620: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
4630: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
4640: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
4650: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4660: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
4670: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
4680: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
4690: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
46a0: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
46b0: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
46c0: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
46d0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
46e0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
46f0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
4700: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
4710: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
4720: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
4730: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
4740: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
4750: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
4760: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
4770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4780: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
4790: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
47a0: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
47b0: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
47c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
47d0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55  UND    12   /* U
47e0: 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e  nknown opcode in
47f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
4800: 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69  ntrol() */.#defi
4810: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20  ne SQLITE_FULL  
4820: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e        13   /* In
4830: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62  sertion failed b
4840: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20  ecause database 
4850: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69  is full */.#defi
4860: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
4870: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e  EN    14   /* Un
4880: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  able to open the
4890: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
48a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
48b0: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20  _PROTOCOL    15 
48c0: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f    /* Database lo
48d0: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f  ck protocol erro
48e0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
48f0: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20  ITE_EMPTY       
4900: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  16   /* Database
4910: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65   is empty */.#de
4920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45  fine SQLITE_SCHE
4930: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20  MA      17   /* 
4940: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  The database sch
4950: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23  ema changed */.#
4960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f  define SQLITE_TO
4970: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f  OBIG      18   /
4980: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  * String or BLOB
4990: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69   exceeds size li
49a0: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mit */.#define S
49b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
49c0: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20    19   /* Abort 
49d0: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e  due to constrain
49e0: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23  t violation */.#
49f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4a00: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f  SMATCH    20   /
4a10: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d  * Data type mism
4a20: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20  atch */.#define 
4a30: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20  SQLITE_MISUSE   
4a40: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61     21   /* Libra
4a50: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63  ry used incorrec
4a60: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tly */.#define S
4a70: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20  QLITE_NOLFS     
4a80: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f    22   /* Uses O
4a90: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73  S features not s
4aa0: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74  upported on host
4ab0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4ac0: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32  TE_AUTH        2
4ad0: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61  3   /* Authoriza
4ae0: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  tion denied */.#
4af0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f  define SQLITE_FO
4b00: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f  RMAT      24   /
4b10: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61  * Auxiliary data
4b20: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f  base format erro
4b30: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4b40: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20  ITE_RANGE       
4b50: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61  25   /* 2nd para
4b60: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4b70: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e  _bind out of ran
4b80: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge */.#define SQ
4b90: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20  LITE_NOTADB     
4ba0: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70   26   /* File op
4bb0: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74  ened that is not
4bc0: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
4bd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4be0: 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 32  TE_NOTICE      2
4bf0: 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74  7   /* Notificat
4c00: 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 65  ions from sqlite
4c10: 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69  3_log() */.#defi
4c20: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
4c30: 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57 61  G     28   /* Wa
4c40: 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69  rnings from sqli
4c50: 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65  te3_log() */.#de
4c60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
4c70: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
4c80: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4c90: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
4ca0: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
4cb0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
4cc0: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
4cd0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
4ce0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
4cf0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
4d00: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
4d10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
4d20: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
4d30: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4d40: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4d50: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4d60: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  ns}.**.** In its
4d70: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4d80: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4d90: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4da0: 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74  rn one of 30 int
4db0: 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20  eger.** [result 
4dc0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
4dd0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
4de0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
4df0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
4e00: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4e10: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4e20: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4e30: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4e40: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4e50: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4e60: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4e70: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4e80: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4e90: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4ea0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
4eb0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
4ec0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
4ed0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
4ee0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
4ef0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
4f00: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4f10: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4f20: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4f30: 72 73 2e 20 54 68 65 73 65 20 5b 65 78 74 65 6e  rs. These [exten
4f40: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4f50: 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72  ] are enabled or
4f60: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20   disabled.** on 
4f70: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63  a per database c
4f80: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20  onnection basis 
4f90: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
4fa0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
4fb0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41  esult_codes()] A
4fc0: 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 65 78 74  PI.  Or, the ext
4fd0: 65 6e 64 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a  ended code for.*
4fe0: 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  * the most recen
4ff0: 74 20 65 72 72 6f 72 20 63 61 6e 20 62 65 20 6f  t error can be o
5000: 62 74 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  btained using.**
5010: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
5020: 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a  ed_errcode()]..*
5030: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5040: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
5050: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5060: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
5070: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5080: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
5090: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50a0: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
50b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50c0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
50d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50e0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
50f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5100: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
5110: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5120: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
5130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5140: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
5150: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5160: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
5170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5180: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
5190: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51a0: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51c0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51e0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5200: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
5210: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5220: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
5230: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
5240: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
5250: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5260: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
5280: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
5290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52a0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
52b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
52c0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
52d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52e0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
52f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
5300: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
5310: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5320: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
5330: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
5340: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
5350: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5360: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
5370: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
5380: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
5390: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
53a0: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
53b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
53c0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
53d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
53e0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
53f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
5400: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
5410: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5420: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
5430: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
5440: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
5450: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5460: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
5470: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5480: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
5490: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
54a0: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
54b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
54c0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
54d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
54e0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
54f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5500: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
5510: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5520: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
5530: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5540: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5550: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5560: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (21<<8)).#define
5570: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45   SQLITE_IOERR_SE
5580: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EK              
5590: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
55a0: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (22<<8)).#define
55b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
55c0: 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20  LETE_NOENT      
55d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
55e0: 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (23<<8)).#define
55f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d   SQLITE_IOERR_MM
5600: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AP              
5610: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5620: 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (24<<8)).#define
5630: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45   SQLITE_IOERR_GE
5640: 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20  TTEMPPATH       
5650: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5660: 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (25<<8)).#define
5670: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f   SQLITE_IOERR_CO
5680: 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20  NVPATH          
5690: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
56a0: 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (26<<8)).#define
56b0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
56c0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
56d0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
56e0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
56f0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
5700: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
5710: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5720: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5730: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53  ne SQLITE_BUSY_S
5740: 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20  NAPSHOT         
5750: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20    (SQLITE_BUSY  
5760: 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66   |  (2<<8)).#def
5770: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5780: 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20  PEN_NOTEMPDIR   
5790: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
57a0: 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  PEN | (1<<8)).#d
57b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
57c0: 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20  TOPEN_ISDIR     
57d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
57e0: 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a  TOPEN | (2<<8)).
57f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5800: 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48  ANTOPEN_FULLPATH
5810: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5820: 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29  ANTOPEN | (3<<8)
5830: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5840: 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41  _CANTOPEN_CONVPA
5850: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5860: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c  _CANTOPEN | (4<<
5870: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5880: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5890: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
58a0: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
58b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
58c0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
58d0: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
58e0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
58f0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5900: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
5910: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
5920: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5930: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5940: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5950: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
5960: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
5970: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5990: 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20  LY_DBMOVED      
59a0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
59b0: 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  LY | (4<<8)).#de
59c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
59d0: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  T_ROLLBACK      
59e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52      (SQLITE_ABOR
59f0: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5a10: 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20  RAINT_CHECK     
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5a30: 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RAINT | (1<<8)).
5a40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5a50: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54  ONSTRAINT_COMMIT
5a60: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43  HOOK   (SQLITE_C
5a70: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c  ONSTRAINT | (2<<
5a80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a90: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f  TE_CONSTRAINT_FO
5aa0: 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49  REIGNKEY   (SQLI
5ab0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5ac0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5ad0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5ae0: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28  T_FUNCTION     (
5af0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b00: 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  T | (4<<8)).#def
5b10: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5b20: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20  RAINT_NOTNULL   
5b30: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5b40: 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a  RAINT | (5<<8)).
5b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b60: 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52  ONSTRAINT_PRIMAR
5b70: 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  YKEY   (SQLITE_C
5b80: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c  ONSTRAINT | (6<<
5b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5ba0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52  TE_CONSTRAINT_TR
5bb0: 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49  IGGER      (SQLI
5bc0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5bd0: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
5be0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5bf0: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28  T_UNIQUE       (
5c00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c10: 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  T | (8<<8)).#def
5c20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5c30: 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20  RAINT_VTAB      
5c40: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5c50: 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a  RAINT | (9<<8)).
5c60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c70: 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20  ONSTRAINT_ROWID 
5c80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5c90: 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c  ONSTRAINT |(10<<
5ca0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5cb0: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5cc0: 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49  R_WAL      (SQLI
5cd0: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c  TE_NOTICE | (1<<
5ce0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5cf0: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5d00: 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49  R_ROLLBACK (SQLI
5d10: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c  TE_NOTICE | (2<<
5d20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d30: 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49  TE_WARNING_AUTOI
5d40: 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49  NDEX       (SQLI
5d50: 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c  TE_WARNING | (1<
5d60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5d70: 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20 20  ITE_AUTH_USER   
5d80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5d90: 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38  ITE_AUTH | (1<<8
5da0: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
5db0: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
5dc0: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
5dd0: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62  ns.**.** These b
5de0: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  it values are in
5df0: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
5e00: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72  n the.** 3rd par
5e10: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5e20: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5e30: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a  ] interface and.
5e40: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61  ** in the 4th pa
5e50: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
5e60: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
5e70: 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64  n] method..*/.#d
5e80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5e90: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
5ea0: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f     0x00000001  /
5eb0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5ec0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5ee0: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
5ef0: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f     0x00000002  /
5f00: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5f10: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5f20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5f30: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
5f40: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f     0x00000004  /
5f50: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5f60: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5f80: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
5f90: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f     0x00000008  /
5fa0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5fb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5fc0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
5fd0: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f     0x00000010  /
5fe0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6000: 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20  N_AUTOPROXY     
6010: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f     0x00000020  /
6020: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6030: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6040: 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20  N_URI           
6050: 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f     0x00000040  /
6060: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6070: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6090: 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20  N_MEMORY        
60a0: 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f     0x00000080  /
60b0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
60c0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
60d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
60e0: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
60f0: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f     0x00000100  /
6100: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6120: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
6130: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f     0x00000200  /
6140: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6150: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6160: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
6170: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f     0x00000400  /
6180: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
61a0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
61b0: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f     0x00000800  /
61c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
61e0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
61f0: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f     0x00001000  /
6200: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6220: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
6230: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f     0x00002000  /
6240: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6260: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
6270: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f     0x00004000  /
6280: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6290: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
62a0: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20  N_NOMUTEX       
62b0: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f     0x00008000  /
62c0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
62d0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
62e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
62f0: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20  N_FULLMUTEX     
6300: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f     0x00010000  /
6310: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6320: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6340: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  N_SHAREDCACHE   
6350: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f     0x00020000  /
6360: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6370: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6390: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20  N_PRIVATECACHE  
63a0: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f     0x00040000  /
63b0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
63c0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
63d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
63e0: 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  N_WAL           
63f0: 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f     0x00080000  /
6400: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  * VFS only */../
6410: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20  * Reserved:     
6420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6430: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a      0x00F00000 *
6440: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
6450: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63  F: Device Charac
6460: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  teristics.**.** 
6470: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
6480: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
6490: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  d of the [sqlite
64a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
64b0: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20   object returns 
64c0: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
64d0: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20   is a vector of 
64e0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
64f0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
6500: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
6510: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
6520: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
6530: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
6540: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
6550: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6560: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
6570: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
6580: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
6590: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
65a0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
65b0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
65c0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
65d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
65e0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
65f0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
6600: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
6610: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
6620: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
6630: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
6640: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
6650: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
6660: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
6670: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6680: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6690: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
66a0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
66b0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
66c0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
66d0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
66e0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
66f0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
6700: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
6710: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
6720: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
6730: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6740: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
6750: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6760: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
6770: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
6780: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
6790: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
67a0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54   to xWrite().  T
67b0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
67c0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
67d0: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61  ITE property mea
67e0: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72  ns that.** after
67f0: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e   reboot followin
6800: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77  g a crash or pow
6810: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c  er loss, the onl
6820: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20  y bytes in a.** 
6830: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77  file that were w
6840: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70  ritten at the ap
6850: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20  plication level 
6860: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67  might have chang
6870: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61  ed.** and that a
6880: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65  djacent bytes, e
6890: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e  ven bytes within
68a0: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72   the same sector
68b0: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65   are.** guarante
68c0: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67  ed to be unchang
68d0: 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ed.  The SQLITE_
68e0: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
68f0: 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66  E_WHEN_OPEN.** f
6900: 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61  lag indicate tha
6910: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  t a file cannot 
6920: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  be deleted when 
6930: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51  open.  The.** SQ
6940: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6950: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61  ABLE flag indica
6960: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c  tes that the fil
6970: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d  e is on.** read-
6980: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63  only media and c
6990: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
69a0: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73   even by process
69b0: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61  es with.** eleva
69c0: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a  ted privileges..
69d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
69e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6a00: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
6a10: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6a20: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
6a30: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
6a40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a50: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
6a60: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a70: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
6a80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a90: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
6aa0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
6ab0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ac0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
6ad0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6ae0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
6af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6b00: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
6b10: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
6b20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b30: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
6b40: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b50: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
6b60: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6b70: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6b80: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
6b90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6ba0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
6bb0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6bc0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6bd0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6be0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
6bf0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
6c00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6c10: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
6c20: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
6c30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c40: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6c50: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
6c60: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
6c70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6c80: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
6c90: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
6ca0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6cb0: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
6cc0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6cd0: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  2000../*.** CAPI
6ce0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
6cf0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
6d00: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
6d10: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
6d20: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6d30: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6d40: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6d50: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6d60: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6d70: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
6d80: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
6d90: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
6da0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6db0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
6dc0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
6dd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6de0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
6df0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
6e00: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
6e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6e20: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6e30: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6e40: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
6e50: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
6e60: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
6e70: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
6e80: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
6e90: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
6ea0: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
6eb0: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
6ec0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6ed0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
6ee0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
6ef0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6f00: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6f10: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
6f20: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
6f30: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6f40: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
6f50: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
6f60: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
6f70: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
6f80: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
6f90: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
6fa0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
6fb0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
6fc0: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
6fd0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
6fe0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
6ff0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
7000: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
7010: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
7020: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
7030: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
7040: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
7050: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
7060: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
7070: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
7080: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
7090: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
70a0: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
70b0: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
70c0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
70d0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
70e0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
70f0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
7100: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
7110: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
7120: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
7130: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
7140: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
7150: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
7160: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
7170: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
7180: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
7190: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
71a0: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
71b0: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
71c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
71d0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
71e0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
71f0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
7200: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
7210: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
7220: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
7230: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
7240: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
7250: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
7260: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
7270: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
7280: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
7290: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
72a0: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
72b0: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
72c0: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
72d0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
72e0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
72f0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
7300: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
7310: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
7320: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
7330: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
7340: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
7350: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
7360: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
7370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7380: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
7390: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
73a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
73b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
73c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
73d0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
73e0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
73f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7400: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
7410: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
7420: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
7430: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
7440: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
7450: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
7460: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
7470: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
7480: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
7490: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
74a0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
74b0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
74c0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
74d0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
74e0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
74f0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
7500: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
7510: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
7520: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
7530: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7540: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
7550: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
7560: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
7570: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
7580: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
7590: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
75a0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
75b0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
75c0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
75d0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
75e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
75f0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
7600: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
7610: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
7620: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
7630: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7640: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
7650: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
7660: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
7670: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
7680: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7690: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
76a0: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
76b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
76c0: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
76d0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
76e0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
76f0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
7700: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
7710: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
7720: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
7730: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
7740: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
7750: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
7760: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
7770: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
7780: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
7790: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
77a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
77b0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
77c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
77d0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
77e0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
77f0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7800: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
7810: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
7820: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
7830: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
7840: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
7850: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
7860: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
7870: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
7880: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
7890: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
78a0: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
78b0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
78c0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
78d0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
78e0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
78f0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
7900: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
7910: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
7920: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7930: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
7940: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
7950: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
7960: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
7970: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
7980: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
7990: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
79a0: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
79b0: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
79c0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
79d0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
79e0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
79f0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
7a00: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
7a10: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
7a20: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
7a30: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7a40: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
7a50: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
7a60: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
7a70: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
7a80: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
7a90: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
7aa0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
7ab0: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
7ac0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7ad0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7ae0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
7af0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7b00: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7b10: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7b20: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7b30: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7b40: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
7b50: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7b60: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
7b70: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
7b80: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
7b90: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
7ba0: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
7bb0: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
7bc0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
7bd0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
7be0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
7bf0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
7c00: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
7c10: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
7c20: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
7c30: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
7c40: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
7c50: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
7c60: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
7c70: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
7c80: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
7c90: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
7ca0: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
7cb0: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
7cc0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
7cd0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
7ce0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
7cf0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
7d00: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
7d10: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
7d20: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
7d30: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
7d40: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
7d50: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
7d60: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
7d70: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
7d80: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
7d90: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
7da0: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
7db0: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
7dc0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
7dd0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
7de0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
7df0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
7e00: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
7e10: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
7e20: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
7e30: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
7e40: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
7e50: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
7e60: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
7e70: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
7e80: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
7e90: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
7ea0: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
7eb0: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
7ec0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
7ed0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
7ee0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
7ef0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
7f00: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
7f10: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
7f20: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
7f30: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
7f40: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
7f50: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
7f60: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
7f70: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f  odes | list of o
7f80: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
7f90: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
7fa0: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
7fb0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
7fc0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
7fd0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
7fe0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
7ff0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
8000: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
8010: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
8020: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
8030: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
8040: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
8050: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
8060: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
8070: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
8080: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
8090: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
80a0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
80b0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
80c0: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
80d0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
80e0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
80f0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
8100: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
8110: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
8120: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
8130: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
8140: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
8150: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
8160: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8170: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
8180: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
8190: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
81a0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
81b0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
81c0: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
81d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
81e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
81f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8200: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
8210: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8220: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
8230: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8240: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
8250: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8260: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
8270: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8280: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
8290: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
82a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
82b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
82c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
82d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
82e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
82f0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8300: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
8310: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
8320: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8330: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
8340: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
8350: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
8360: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8370: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
8380: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
8390: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
83a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
83b0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
83c0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
83d0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
83e0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
83f0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
8400: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
8410: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
8420: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
8430: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
8440: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8450: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8460: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
8470: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
8480: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8490: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
84a0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
84b0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
84c0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
84d0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
84e0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
84f0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
8500: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8510: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
8520: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8530: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8540: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
8550: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
8560: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
8570: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
8580: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
8590: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
85a0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
85b0: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
85c0: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
85d0: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
85e0: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
85f0: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
8600: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
8610: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8620: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
8630: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
8640: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
8650: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8660: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
8670: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
8680: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
8690: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
86a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
86b0: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
86c0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
86d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
86e0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
86f0: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
8700: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
8710: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8720: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
8730: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
8740: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8750: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8760: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
8770: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
8780: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
8790: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
87a0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
87b0: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
87c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
87d0: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
87e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
87f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8800: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
8810: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
8820: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8830: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
8840: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
8850: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8860: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8870: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
8880: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8890: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
88a0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
88b0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
88c0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
88d0: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
88e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
88f0: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
8900: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
8910: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
8920: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8930: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8940: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
8950: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
8960: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
8970: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8980: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
8990: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
89a0: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
89b0: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
89c0: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
89d0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
89e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
89f0: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
8a00: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
8a10: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
8a20: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
8a30: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
8a40: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
8a50: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
8a60: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
8a70: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8a80: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8a90: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
8aa0: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
8ab0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8ac0: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
8ad0: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
8ae0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
8af0: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8b00: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8b10: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
8b20: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8b30: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8b40: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
8b50: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
8b60: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
8b70: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
8b80: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
8b90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
8ba0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
8bb0: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b  rol Opcodes.** K
8bc0: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63  EYWORDS: {file c
8bd0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20  ontrol opcodes} 
8be0: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
8bf0: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  code}.**.** Thes
8c00: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
8c10: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
8c20: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
8c30: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
8c40: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
8c50: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
8c60: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
8c70: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8c80: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
8c90: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ace..**.** <ul>.
8ca0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8cb0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
8cc0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8cd0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8ce0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8cf0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
8d00: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
8d10: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
8d20: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
8d30: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
8d40: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
8d50: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
8d60: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
8d70: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
8d80: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
8d90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8da0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
8db0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
8dc0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8dd0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
8de0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
8df0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
8e00: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
8e10: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
8e20: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
8e30: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f  testing and is o
8e40: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68  nly available wh
8e50: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  en the SQLITE_TE
8e60: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  ST.** compile-ti
8e70: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  me option is use
8e80: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
8e90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
8ea0: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
8eb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
8ec0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
8ed0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
8ee0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
8ef0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
8f00: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
8f10: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
8f20: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
8f30: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
8f40: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
8f50: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
8f60: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
8f70: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
8f80: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
8f90: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
8fa0: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
8fb0: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
8fc0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
8fd0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
8fe0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
8ff0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
9000: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
9010: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
9020: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
9030: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9040: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9050: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
9060: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9070: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
9080: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
9090: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
90a0: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
90b0: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
90c0: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
90d0: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
90e0: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
90f0: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
9100: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
9110: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9120: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
9130: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
9140: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
9150: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
9160: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
9170: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
9180: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
9190: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
91a0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
91b0: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
91c0: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
91d0: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
91e0: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
91f0: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
9200: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
9210: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
9220: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
9230: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9240: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9250: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
9260: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9270: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
9280: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
9290: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
92a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
92b0: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
92c0: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74  ated with a part
92d0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
92e0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
92f0: 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  See the [sqlite3
9300: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9310: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
9320: 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
9330: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
9340: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9350: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
9360: 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67  TED]].** No long
9370: 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a  er in use..**.**
9380: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9390: 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68  NTL_SYNC]].** Th
93a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
93b0: 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20  SYNC] opcode is 
93c0: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
93d0: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61  ally by SQLite a
93e0: 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68  nd.** sent to th
93f0: 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c  e VFS immediatel
9400: 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79  y before the xSy
9410: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  nc method is inv
9420: 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74  oked on a.** dat
9430: 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72  abase file descr
9440: 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68  iptor. Or, if th
9450: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
9460: 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a  s not invoked .*
9470: 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73  * because the us
9480: 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65  er has configure
9490: 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a  d SQLite with .*
94a0: 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  * [PRAGMA synchr
94b0: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73  onous | PRAGMA s
94c0: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20  ynchronous=OFF] 
94d0: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e  it is invoked in
94e0: 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68   place .** of th
94f0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20  e xSync method. 
9500: 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74  In most cases, t
9510: 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
9520: 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a  ent passed with.
9530: 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  ** this file-con
9540: 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f  trol is NULL. Ho
9550: 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61  wever, if the da
9560: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62  tabase file is b
9570: 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61  eing synced.** a
9580: 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74  s part of a mult
9590: 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69  i-database commi
95a0: 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  t, the argument 
95b0: 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d  points to a nul-
95c0: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
95d0: 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
95e0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  the transactions
95f0: 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20   master-journal 
9600: 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73  file name. VFSes
9610: 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74   that .** do not
9620: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9630: 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  l should silentl
9640: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
9650: 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f  code. Applicatio
9660: 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f  ns .** should no
9670: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
9680: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9690: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65  with this opcode
96a0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
96b0: 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65   .** disrupt the
96c0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
96d0: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
96e0: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75  Ses that do requ
96f0: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20  ire it.  .**.** 
9700: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9710: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
9720: 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  WO]].** The [SQL
9730: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
9740: 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64  _PHASETWO] opcod
9750: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
9760: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
9770: 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20  ite.** and sent 
9780: 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72  to the VFS after
9790: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68   a transaction h
97a0: 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65  as been committe
97b0: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a  d immediately.**
97c0: 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20   but before the 
97d0: 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f  database is unlo
97e0: 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74  cked. VFSes that
97f0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
9800: 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75  s signal.** shou
9810: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9820: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
9830: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
9840: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20  uld not call.** 
9850: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9860: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9870: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9880: 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70  ng so may disrup
9890: 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74  t the .** operat
98a0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
98b0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
98c0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
98d0: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
98e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
98f0: 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20  2_AV_RETRY]].** 
9900: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9910: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
9920: 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  Y] opcode is use
9930: 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61  d to configure a
9940: 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72  utomatic.** retr
9950: 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74  y counts and int
9960: 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61  ervals for certa
9970: 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72  in disk I/O oper
9980: 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a  ations for the.*
9990: 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20  * windows [VFS] 
99a0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76  in order to prov
99b0: 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69  ide robustness i
99c0: 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  n the presence o
99d0: 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20  f.** anti-virus 
99e0: 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65  programs.  By de
99f0: 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f  fault, the windo
9a00: 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72  ws VFS will retr
9a10: 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20  y file read,.** 
9a20: 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20  file write, and 
9a30: 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72  file delete oper
9a40: 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20  ations up to 10 
9a50: 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65  times, with a de
9a60: 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c  lay.** of 25 mil
9a70: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65  liseconds before
9a80: 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79   the first retry
9a90: 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65   and with the de
9aa0: 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a  lay increasing.*
9ab0: 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e  * by an addition
9ac0: 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  al 25 millisecon
9ad0: 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62  ds with each sub
9ae0: 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20  sequent retry.  
9af0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  This.** opcode a
9b00: 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20  llows these two 
9b10: 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69  values (10 retri
9b20: 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73  es and 25 millis
9b30: 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29  econds of delay)
9b40: 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74  .** to be adjust
9b50: 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20  ed.  The values 
9b60: 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20  are changed for 
9b70: 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e  all database con
9b80: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  nections.** with
9b90: 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63  in the same proc
9ba0: 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ess.  The argume
9bb0: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
9bc0: 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74  to an array of t
9bd0: 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77  wo.** integers w
9be0: 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69  here the first i
9bf0: 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77  nteger i the new
9c00: 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64   retry count and
9c10: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69   the second.** i
9c20: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65  nteger is the de
9c30: 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20  lay.  If either 
9c40: 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74  integer is negat
9c50: 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65  ive, then the se
9c60: 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20  tting.** is not 
9c70: 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74  changed but inst
9c80: 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61  ead the prior va
9c90: 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74  lue of that sett
9ca0: 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  ing is written.*
9cb0: 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79  * into the array
9cc0: 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67   entry, allowing
9cd0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74   the current ret
9ce0: 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62  ry settings to b
9cf0: 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65  e.** interrogate
9d00: 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20  d.  The zDbName 
9d10: 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e  parameter is ign
9d20: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ored..**.** <li>
9d30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
9d40: 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20  ERSIST_WAL]].** 
9d50: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9d60: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20  TL_PERSIST_WAL] 
9d70: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9d80: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
9d90: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
9da0: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68   [WAL | Write Ah
9db0: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67  ead Log] setting
9dc0: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
9dd0: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20  he auxiliary.** 
9de0: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20  write ahead log 
9df0: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
9e00: 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72  y files used for
9e10: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
9e20: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f  trol.** are auto
9e30: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
9e40: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73  d when the lates
9e50: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  t connection to 
9e60: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
9e70: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67  closes.  Setting
9e80: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
9e90: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73  mode causes thos
9ea0: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69  e files to persi
9eb0: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73  st after.** clos
9ec0: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74  e.  Persisting t
9ed0: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66  he files is usef
9ee0: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72  ul when other pr
9ef0: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20  ocesses that do 
9f00: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74  not.** have writ
9f10: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20  e permission on 
9f20: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f  the directory co
9f30: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74  ntaining the dat
9f40: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a  abase file want.
9f50: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64  ** to read the d
9f60: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73  atabase file, as
9f70: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61   the WAL and sha
9f80: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9f90: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69   must exist.** i
9fa0: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20  n order for the 
9fb0: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  database to be r
9fc0: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f  eadable.  The fo
9fd0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
9fe0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
9ff0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a000: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a010: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a020: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a030: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a040: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a050: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
a060: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
a070: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  ble persistent.*
a080: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20  * WAL mode.  If 
a090: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
a0a0: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
a0b0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
a0c0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41  he current.** WA
a0d0: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65  L persistence se
a0e0: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
a0f0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a100: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a110: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a120: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
a130: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a140: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
a150: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
a160: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
a170: 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65  t "powersafe-ove
a180: 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57  rwrite" or "PSOW
a190: 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20  " setting.  The 
a1a0: 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20  PSOW setting.** 
a1b0: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b  determines the [
a1c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
a1d0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a1e0: 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20  ] bit of the.** 
a1f0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
a200: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20  istics methods. 
a210: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
a220: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
a230: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a240: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
a250: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
a260: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
a270: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
a280: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
a290: 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  isable zero-dama
a2a0: 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  ge mode or 1 to 
a2b0: 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  enable zero-dama
a2c0: 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20  ge.** mode.  If 
a2d0: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
a2e0: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
a2f0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
a300: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65  he current.** ze
a310: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73  ro-damage mode s
a320: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
a330: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a340: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
a350: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a360: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  TL_OVERWRITE] op
a370: 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  code is invoked 
a380: 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20  by SQLite after 
a390: 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69  opening.** a wri
a3a0: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  te transaction t
a3b0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c  o indicate that,
a3c0: 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f   unless it is ro
a3d0: 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f  lled back for so
a3e0: 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68  me.** reason, th
a3f0: 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73  e entire databas
a400: 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f  e file will be o
a410: 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68  verwritten by th
a420: 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72  e current .** tr
a430: 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20  ansaction. This 
a440: 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55  is used by VACUU
a450: 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  M operations..**
a460: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a470: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d  _FCNTL_VFSNAME]]
a480: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a490: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20  _FCNTL_VFSNAME] 
a4a0: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
a4b0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
a4c0: 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c   names of.** all
a4d0: 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20   [VFSes] in the 
a4e0: 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20  VFS stack.  The 
a4f0: 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c  names are of all
a500: 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74   VFS shims and t
a510: 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74  he.** final bott
a520: 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65  om-level VFS are
a530: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
a540: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
a550: 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
a560: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68  malloc()] and th
a570: 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72  e result is stor
a580: 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20  ed in the char* 
a590: 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74  variable.** that
a5a0: 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
a5b0: 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65  meter of [sqlite
a5c0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a5d0: 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20  ] points to..** 
a5e0: 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65  The caller is re
a5f0: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72  sponsible for fr
a600: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79  eeing the memory
a610: 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20   when done.  As 
a620: 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65  with.** all file
a630: 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73  -control actions
a640: 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75  , there is no gu
a650: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69  arantee that thi
a660: 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a  s will actually.
a670: 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20  ** do anything. 
a680: 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20   Callers should 
a690: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63  initialize the c
a6a0: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f  har* variable to
a6b0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
a6c0: 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20  er in case this 
a6d0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
a6e0: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e  not implemented.
a6f0: 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74    This file-cont
a700: 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64  rol.** is intend
a710: 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69  ed for diagnosti
a720: 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  c use only..**.*
a730: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a740: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
a750: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
a760: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
a770: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
a780: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a790: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
a7a0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
a7b0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
a7c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
a7d0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
a7e0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
a7f0: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
a800: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
a810: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
a820: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
a830: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a840: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a850: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
a860: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
a870: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
a880: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
a890: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
a8a0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
a8b0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
a8c0: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
a8d0: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
a8e0: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
a8f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
a900: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
a910: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
a920: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
a930: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
a940: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a950: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
a960: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
a970: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
a980: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
a990: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
a9a0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
a9b0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
a9c0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
a9d0: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
a9e0: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
a9f0: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
aa00: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
aa10: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
aa20: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
aa30: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
aa40: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
aa50: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
aa60: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
aa70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
aa80: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
aa90: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
aaa0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
aab0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
aac0: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
aad0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
aae0: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
aaf0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
ab00: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
ab10: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
ab20: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
ab30: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
ab40: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
ab50: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
ab60: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
ab70: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
ab80: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c  atement if resul
ab90: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c  t string is NULL
aba0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e  , or that return
abb0: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
abc0: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  he result string
abd0: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   if the string i
abe0: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e  s non-NULL..** ^
abf0: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
ac00: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ac10: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
ac20: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
ac30: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
ac40: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
ac50: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
ac60: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
ac70: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
ac80: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
ac90: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
aca0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
acb0: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
acc0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
acd0: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
ace0: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
acf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ad00: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
ad10: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
ad20: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
ad30: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
ad40: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
ad50: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
ad60: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
ad70: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
ad80: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
ad90: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ada0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
adb0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
adc0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
add0: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
ade0: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
adf0: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
ae00: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
ae10: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
ae20: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
ae30: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
ae40: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
ae50: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
ae60: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
ae70: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
ae80: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
ae90: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
aea0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
aeb0: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
aec0: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
aed0: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
aee0: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
aef0: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
af00: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
af10: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
af20: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
af30: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
af40: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
af50: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
af60: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
af70: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
af80: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
af90: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
afa0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
afb0: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
afc0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
afd0: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
afe0: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
aff0: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
b000: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
b010: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
b020: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
b030: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
b040: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
b050: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b060: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
b070: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
b080: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
b090: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b0a0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
b0b0: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
b0c0: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
b0d0: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
b0e0: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
b0f0: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
b100: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
b110: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
b120: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b130: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
b140: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
b150: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
b160: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
b170: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
b180: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
b190: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b1a0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
b1b0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
b1c0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
b1d0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
b1e0: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
b1f0: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
b200: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
b210: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
b220: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
b230: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
b240: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b250: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
b260: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b270: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
b280: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b290: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
b2a0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
b2b0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
b2c0: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
b2d0: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
b2e0: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
b2f0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
b300: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
b310: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
b320: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
b330: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
b340: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b350: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
b360: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
b370: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
b380: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
b390: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
b3a0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
b3b0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
b3c0: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
b3d0: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
b3e0: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
b3f0: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
b400: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
b410: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
b420: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
b430: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
b440: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
b450: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
b460: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
b470: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
b480: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
b490: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
b4a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
b4b0: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
b4c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b4d0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
b4e0: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
b4f0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
b500: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
b510: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
b520: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
b530: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
b540: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
b550: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
b560: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
b570: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
b580: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
b590: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
b5a0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
b5b0: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
b5c0: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
b5d0: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
b5e0: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
b5f0: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
b600: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
b610: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
b620: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
b630: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
b640: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
b650: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b660: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
b670: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b680: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
b690: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
b6a0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
b6b0: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
b6c0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
b6d0: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
b6e0: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
b6f0: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
b700: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
b710: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
b720: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
b730: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
b740: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
b750: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
b760: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
b770: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b780: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
b790: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
b7a0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
b7b0: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
b7c0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
b7d0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
b7e0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
b7f0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
b800: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
b810: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
b820: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
b830: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
b840: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
b850: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
b860: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
b870: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
b880: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
b890: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
b8a0: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
b8b0: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  efined..**.** <l
b8c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b8d0: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20  _WAL_BLOCK]].** 
b8e0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b8f0: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20  L_WAL_BLOCK] is 
b900: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
b910: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69  VFS layer that i
b920: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64  t might.** be ad
b930: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c  vantageous to bl
b940: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  ock on the next 
b950: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20  WAL lock if the 
b960: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65  lock is not imme
b970: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c  diately.** avail
b980: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73  able.  The WAL s
b990: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20  ubsystem issues 
b9a0: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69  this signal duri
b9b0: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75  ng rare.** circu
b9c0: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65  mstances in orde
b9d0: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c  r to fix a probl
b9e0: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79  em with priority
b9f0: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41   inversion..** A
ba00: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
ba10: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  ld <em>not</em> 
ba20: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  use this file-co
ba30: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ntrol..**.** <li
ba40: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
ba50: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20  ZIPVFS]].** The 
ba60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
ba70: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20  PVFS] opcode is 
ba80: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a  implemented by z
ba90: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20  ipvfs only. All 
baa0: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f  other.** VFS sho
bab0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
bac0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74  E_NOTFOUND for t
bad0: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a  his opcode..**.*
bae0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
baf0: 43 4e 54 4c 5f 4f 54 41 5d 5d 0a 2a 2a 20 54 68  CNTL_OTA]].** Th
bb00: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bb10: 4f 54 41 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  OTA] opcode is i
bb20: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
bb30: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73  e special VFS us
bb40: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 4f 54 41  ed by.** the OTA
bb50: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e   extension only.
bb60: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20    All other VFS 
bb70: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
bb80: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
bb90: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65  r.** this opcode
bba0: 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .  .** </ul>.*/.
bbb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bbc0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
bbd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
bbe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bbf0: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
bc00: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
bc10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bc20: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
bc30: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
bc40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bc50: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
bc60: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
bc70: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bc80: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
bc90: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
bca0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bcb0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
bcc0: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
bcd0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
bce0: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
bcf0: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
bd00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
bd10: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
bd20: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
bd30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bd40: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
bd50: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
bd60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
bd70: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
bd80: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
bd90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
bda0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
bdb0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
bdc0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
bdd0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
bde0: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
bdf0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
be00: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
be10: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
be20: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
be30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
be40: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
be50: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
be60: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
be70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
be80: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
be90: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
bea0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
beb0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
bec0: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
bed0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bee0: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
bef0: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
bf00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bf10: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
bf20: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
bf30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bf40: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
bf50: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
bf60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bf70: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
bf80: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69          22.#defi
bf90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bfa0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
bfb0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e         23.#defin
bfc0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
bfd0: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20  AL_BLOCK        
bfe0: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65        24.#define
bff0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49   SQLITE_FCNTL_ZI
c000: 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20  PVFS            
c010: 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20       25.#define 
c020: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 54 41  SQLITE_FCNTL_OTA
c030: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c040: 20 20 20 20 32 36 0a 0a 2f 2a 20 64 65 70 72 65      26../* depre
c050: 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23  cated names */.#
c060: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45  define SQLITE_GE
c070: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
c080: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
c090: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_GET_LOCKPROXYF
c0a0: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
c0b0: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
c0c0: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
c0d0: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
c0e0: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
c0f0: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
c100: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53  NO             S
c110: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
c120: 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  _ERRNO.../*.** C
c130: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
c140: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  andle.**.** The 
c150: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
c160: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
c170: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
c180: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
c190: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
c1a0: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
c1b0: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
c1c0: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
c1d0: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
c1e0: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
c1f0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
c200: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
c210: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
c220: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
c230: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
c240: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
c250: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
c260: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
c270: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
c280: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
c290: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
c2a0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
c2b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
c2c0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
c2d0: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
c2e0: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
c2f0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
c300: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
c310: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
c320: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
c330: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
c340: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
c350: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
c360: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
c370: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
c380: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
c390: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20   file system".  
c3a0: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20  See.** the [VFS 
c3b0: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74  | VFS documentat
c3c0: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72  ion] for further
c3d0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
c3e0: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
c3f0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
c400: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
c410: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
c420: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
c430: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
c440: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
c450: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
c460: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
c470: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
c480: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
c490: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
c4a0: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
c4b0: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
c4c0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
c4d0: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
c4e0: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
c4f0: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
c500: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
c510: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
c520: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
c530: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
c540: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
c550: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
c560: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
c570: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
c580: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
c590: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
c5a0: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
c5b0: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
c5c0: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
c5d0: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
c5e0: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
c5f0: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
c600: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
c610: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
c620: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
c630: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
c640: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
c650: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
c660: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
c670: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
c680: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
c690: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
c6a0: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
c6b0: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
c6c0: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
c6d0: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
c6e0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
c6f0: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
c700: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
c710: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
c720: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
c730: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
c740: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
c750: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
c760: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
c770: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
c780: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
c790: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
c7a0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
c7b0: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
c7c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
c7d0: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
c7e0: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
c7f0: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
c800: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
c810: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
c820: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
c830: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
c840: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
c850: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
c860: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
c870: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
c880: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
c890: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
c8a0: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
c8b0: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
c8c0: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
c8d0: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
c8e0: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
c8f0: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
c900: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
c910: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
c920: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
c930: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
c940: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
c950: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
c960: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
c970: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
c980: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
c990: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
c9a0: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
c9b0: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
c9c0: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
c9d0: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
c9e0: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
c9f0: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
ca00: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
ca10: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
ca20: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
ca30: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
ca40: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
ca50: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
ca60: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
ca70: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
ca80: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
ca90: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
caa0: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
cab0: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
cac0: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
cad0: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
cae0: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
caf0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
cb00: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
cb10: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
cb20: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
cb30: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
cb40: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
cb50: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
cb60: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
cb70: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
cb80: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
cb90: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
cba0: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
cbb0: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
cbc0: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
cbd0: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
cbe0: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
cbf0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
cc00: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
cc10: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
cc20: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
cc30: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
cc40: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
cc50: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
cc60: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
cc70: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
cc80: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
cc90: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
cca0: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
ccb0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
ccc0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
ccd0: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
cce0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
ccf0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
cd00: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
cd10: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
cd20: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
cd30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
cd40: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
cd50: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
cd60: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
cd70: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
cd80: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
cd90: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
cda0: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
cdb0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
cdc0: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
cdd0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
cde0: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
cdf0: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
ce00: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
ce10: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
ce20: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
ce30: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
ce40: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
ce50: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
ce60: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
ce70: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
ce80: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
ce90: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
cea0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
ceb0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
cec0: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
ced0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cee0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
cef0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
cf00: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
cf10: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
cf20: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
cf30: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
cf40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
cf50: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
cf60: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cf70: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
cf80: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
cf90: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
cfa0: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
cfb0: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
cfc0: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
cfd0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
cfe0: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
cff0: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
d000: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
d010: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
d020: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
d030: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
d040: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
d050: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
d060: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
d070: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
d080: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
d090: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
d0a0: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
d0b0: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
d0c0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
d0d0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
d0e0: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
d0f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
d100: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
d110: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
d120: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
d130: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
d140: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
d150: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
d160: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
d170: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
d180: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
d190: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
d1a0: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
d1b0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
d1c0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
d1d0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
d1e0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
d1f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
d200: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d210: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
d220: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
d230: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
d240: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
d250: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
d260: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
d270: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
d280: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
d290: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
d2a0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
d2b0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
d2c0: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
d2d0: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
d2e0: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
d2f0: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
d300: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
d310: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
d320: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
d330: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
d340: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
d350: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
d360: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
d370: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
d380: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
d390: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
d3a0: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
d3b0: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
d3c0: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
d3d0: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
d3e0: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
d3f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
d400: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
d410: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
d420: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
d430: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
d440: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
d450: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
d460: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
d470: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
d480: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
d490: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
d4a0: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
d4b0: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
d4c0: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
d4d0: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
d4e0: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
d4f0: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
d500: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
d510: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
d520: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
d530: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
d540: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
d550: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
d560: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
d570: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
d580: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
d590: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
d5a0: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
d5b0: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
d5c0: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
d5d0: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
d5e0: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
d5f0: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
d600: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
d610: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
d620: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
d630: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
d640: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
d650: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
d660: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
d670: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
d680: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
d690: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
d6a0: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
d6b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
d6c0: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
d6d0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
d6e0: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
d6f0: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
d700: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
d710: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
d720: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
d730: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
d740: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
d750: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
d760: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
d770: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
d780: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
d790: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
d7a0: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
d7b0: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
d7c0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
d7d0: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
d7e0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
d7f0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
d800: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
d810: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
d820: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
d830: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
d840: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
d850: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
d860: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
d870: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
d880: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
d890: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
d8a0: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
d8b0: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
d8c0: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
d8d0: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
d8e0: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
d8f0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
d900: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
d910: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
d920: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
d930: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
d940: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
d950: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
d960: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
d970: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
d980: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
d990: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
d9a0: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
d9b0: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
d9c0: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
d9d0: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
d9e0: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
d9f0: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
da00: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
da10: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
da20: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
da30: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
da40: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
da50: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
da60: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
da70: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
da80: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
da90: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
daa0: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
dab0: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
dac0: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
dad0: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
dae0: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
daf0: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
db00: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
db10: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
db20: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
db30: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
db40: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
db50: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
db60: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
db70: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
db80: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
db90: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
dba0: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
dbb0: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
dbc0: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
dbd0: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
dbe0: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
dbf0: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
dc00: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
dc10: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
dc20: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
dc30: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
dc40: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
dc50: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
dc60: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
dc70: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
dc80: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
dc90: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
dca0: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
dcb0: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
dcc0: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
dcd0: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
dce0: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
dcf0: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
dd00: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
dd10: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
dd20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
dd30: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
dd40: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
dd50: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
dd60: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
dd70: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
dd80: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
dd90: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
dda0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
ddb0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
ddc0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
ddd0: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
dde0: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
ddf0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
de00: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
de10: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
de20: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
de30: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
de40: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
de50: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
de60: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
de70: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
de80: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
de90: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
dea0: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
deb0: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
dec0: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
ded0: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
dee0: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
def0: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
df00: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
df10: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
df20: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
df30: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
df40: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
df50: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
df60: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
df70: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
df80: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
df90: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
dfa0: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
dfb0: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
dfc0: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
dfd0: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
dfe0: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
dff0: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
e000: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
e010: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
e020: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
e030: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
e040: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
e050: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
e060: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
e070: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
e080: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
e090: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
e0a0: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
e0b0: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
e0c0: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
e0d0: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
e0e0: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
e0f0: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
e100: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
e110: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
e120: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
e130: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
e140: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
e150: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
e160: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
e170: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
e180: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
e190: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
e1a0: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
e1b0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
e1c0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
e1d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
e1e0: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
e1f0: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
e200: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
e210: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
e220: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
e230: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
e240: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
e250: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
e260: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
e270: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
e280: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
e290: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
e2a0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
e2b0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
e2c0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
e2d0: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
e2e0: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
e2f0: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
e300: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
e310: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
e320: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
e330: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
e340: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
e350: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e360: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
e370: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
e380: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
e390: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
e3a0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
e3b0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
e3c0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e3d0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
e3e0: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
e3f0: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
e400: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e410: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
e420: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
e430: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
e440: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
e450: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e460: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
e470: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
e480: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
e490: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
e4a0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e4b0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
e4c0: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
e4d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e4e0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
e4f0: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
e500: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
e510: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
e520: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
e530: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
e540: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
e550: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e560: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
e570: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
e580: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
e590: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
e5a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
e5b0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
e5c0: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
e5d0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
e5e0: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
e5f0: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
e600: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
e610: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
e620: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
e630: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
e640: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e650: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
e660: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
e670: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
e680: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
e690: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
e6a0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
e6b0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
e6c0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
e6d0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
e6e0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
e6f0: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
e700: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e710: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e720: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
e730: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
e740: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
e750: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
e760: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
e770: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
e780: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
e790: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
e7a0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e7b0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
e7c0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
e7d0: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
e7e0: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
e7f0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e800: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e810: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
e820: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
e830: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
e840: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e850: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
e860: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
e870: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
e880: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
e890: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
e8a0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
e8b0: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
e8c0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
e8d0: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
e8e0: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
e8f0: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
e900: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
e910: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
e920: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
e930: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
e940: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
e950: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
e960: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
e970: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
e980: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
e990: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
e9a0: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
e9b0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
e9c0: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
e9d0: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
e9e0: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
e9f0: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
ea00: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ea10: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
ea20: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
ea30: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
ea40: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ea50: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
ea60: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
ea70: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
ea80: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
ea90: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
eaa0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
eab0: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
eac0: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
ead0: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
eae0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
eaf0: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
eb00: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
eb10: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
eb20: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
eb30: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
eb40: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
eb50: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
eb60: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
eb70: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
eb80: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
eb90: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
eba0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
ebb0: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
ebc0: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
ebd0: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
ebe0: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
ebf0: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
ec00: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
ec10: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
ec20: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
ec30: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
ec40: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
ec50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
ec60: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
ec70: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
ec80: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
ec90: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
eca0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
ecb0: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
ecc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
ecd0: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
ece0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ecf0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
ed00: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
ed10: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
ed20: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
ed30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
ed40: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
ed50: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
ed60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ed70: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
ed80: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
ed90: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
eda0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
edb0: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
edc0: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
edd0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
ede0: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
edf0: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
ee00: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
ee10: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
ee20: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
ee30: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
ee40: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
ee50: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
ee60: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
ee70: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
ee80: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
ee90: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
eea0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
eeb0: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
eec0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
eed0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
eee0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
eef0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
ef00: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
ef10: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
ef20: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
ef30: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
ef40: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
ef50: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
ef60: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
ef70: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
ef80: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
ef90: 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
efa0: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
efb0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
efc0: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
efd0: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
efe0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
eff0: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
f000: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
f010: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
f020: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
f030: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
f040: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
f050: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
f060: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
f070: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
f080: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
f090: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
f0a0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
f0b0: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
f0c0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
f0d0: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
f0e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
f0f0: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
f100: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
f110: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
f120: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
f130: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
f140: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
f150: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
f160: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
f170: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
f180: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
f190: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
f1a0: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
f1b0: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
f1c0: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
f1d0: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
f1e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f1f0: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
f200: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
f210: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
f220: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
f230: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
f240: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f250: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
f260: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
f270: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
f280: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
f290: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
f2a0: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
f2b0: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
f2c0: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
f2d0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
f2e0: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
f2f0: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
f300: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
f310: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
f320: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
f330: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
f340: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
f350: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
f360: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
f370: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
f380: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
f390: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
f3a0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
f3b0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
f3c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f3d0: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
f3e0: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
f3f0: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
f400: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
f410: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
f420: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
f430: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
f440: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
f450: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
f460: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
f470: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f480: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
f490: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
f4a0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f4b0: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
f4c0: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
f4d0: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
f4e0: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
f4f0: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
f500: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
f510: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
f520: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
f530: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
f540: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f550: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
f560: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
f570: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
f580: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
f590: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
f5a0: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
f5b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
f5c0: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
f5d0: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
f5e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f5f0: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
f600: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
f610: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
f620: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
f630: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
f640: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
f650: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
f660: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f670: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
f680: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
f690: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f6a0: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
f6b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f6c0: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
f6d0: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
f6e0: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
f6f0: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
f700: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
f710: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
f720: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
f730: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
f740: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
f750: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
f760: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
f770: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
f780: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
f790: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
f7a0: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
f7b0: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
f7c0: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
f7d0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
f7e0: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
f7f0: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
f800: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
f810: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
f820: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f830: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f840: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
f850: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
f860: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
f870: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
f880: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f890: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
f8a0: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
f8b0: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
f8c0: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
f8d0: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
f8e0: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
f8f0: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
f900: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
f910: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
f920: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
f930: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
f940: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f950: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
f960: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
f970: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
f980: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
f990: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
f9a0: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
f9b0: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
f9c0: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
f9d0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f9e0: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
f9f0: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
fa00: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
fa10: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
fa20: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
fa30: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
fa40: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
fa50: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
fa60: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
fa70: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
fa80: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
fa90: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
faa0: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
fab0: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
fac0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
fad0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
fae0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
faf0: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
fb00: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
fb10: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
fb20: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
fb30: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
fb40: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
fb50: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
fb60: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
fb70: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
fb80: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
fb90: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
fba0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
fbb0: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
fbc0: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
fbd0: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
fbe0: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
fbf0: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
fc00: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fc10: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
fc20: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
fc30: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
fc40: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
fc50: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
fc60: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
fc70: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
fc80: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
fc90: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
fca0: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
fcb0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
fcc0: 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
fcd0: 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
fce0: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
fcf0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
fd00: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
fd10: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
fd20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
fd30: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
fd40: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
fd50: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
fd60: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
fd70: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
fd80: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
fd90: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
fda0: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
fdb0: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
fdc0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
fdd0: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
fde0: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
fdf0: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
fe00: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
fe10: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
fe20: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
fe30: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
fe40: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
fe50: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
fe60: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
fe70: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
fe80: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
fe90: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
fea0: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
feb0: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
fec0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
fed0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
fee0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
fef0: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
ff00: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
ff10: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
ff20: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
ff30: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
ff40: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
ff50: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
ff60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ff70: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
ff80: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
ff90: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
ffa0: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
ffb0: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
ffc0: 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
ffd0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ffe0: 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
fff0: 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
10000 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
10010 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
10020 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
10030 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
10040 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
10050 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
10060 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
10070 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
10080 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
10090 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
100a0 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
100b0 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
100c0 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
100d0 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
100e0 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
100f0 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
10100 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
10110 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
10120 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
10130 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
10140 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
10150 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
10160 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
10170 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
10180 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
10190 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
101a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
101b0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
101c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
101d0 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
101e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
101f0 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
10200 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
10210 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
10220 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54  ailure..*/.SQLIT
10230 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
10240 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
10250 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
10260 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
10270 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
10280 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10290 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  n(void);.SQLITE_
102a0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
102b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f  TDCALL sqlite3_o
102c0 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51  s_init(void);.SQ
102d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
102e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
102f0 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
10300 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10310 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
10320 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
10330 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
10340 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
10350 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
10360 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
10370 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
10380 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
10390 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
103a0 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
103b0 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
103c0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
103d0 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
103e0 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
103f0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
10400 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
10410 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
10420 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
10430 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
10440 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
10450 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
10460 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
10470 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
10480 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
10490 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
104a0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
104b0 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
104c0 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
104d0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
104e0 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
104f0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10500 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
10510 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
10520 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
10530 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
10540 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
10550 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
10560 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
10570 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
10580 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
10590 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
105a0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
105b0 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
105c0 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
105d0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
105e0 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
105f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10600 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
10610 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10620 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
10630 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
10640 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
10650 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
10660 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
10670 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
10680 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
10690 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
106a0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
106b0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
106c0 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
106d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
106e0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
106f0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
10700 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
10710 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10720 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
10730 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
10740 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
10750 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
10760 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
10770 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
10780 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
10790 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
107a0 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
107b0 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
107c0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
107d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
107e0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
107f0 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
10800 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
10810 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
10820 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
10830 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
10840 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
10850 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
10860 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
10870 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
10880 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
10890 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
108a0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
108b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
108c0 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c  int SQLITE_CDECL
108d0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
108e0 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
108f0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
10900 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
10910 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
10920 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
10930 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10940 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
10950 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
10960 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
10970 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
10980 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
10990 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
109a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
109b0 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
109c0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
109d0 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
109e0 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
109f0 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
10a00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10a10 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
10a20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10a30 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
10a40 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
10a50 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
10a60 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
10a70 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
10a80 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
10a90 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
10aa0 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
10ab0 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
10ac0 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
10ad0 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
10ae0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10af0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
10b00 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
10b10 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
10b20 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
10b30 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
10b40 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
10b50 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
10b60 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
10b70 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
10b80 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
10b90 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
10ba0 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
10bb0 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ssful..*/.SQLITE
10bc0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
10bd0 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 64 62  CDECL sqlite3_db
10be0 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
10bf0 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
10c00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10c10 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
10c20 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
10c30 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
10c40 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
10c50 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
10c60 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
10c70 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
10c80 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
10c90 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
10ca0 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
10cb0 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
10cc0 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
10cd0 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
10ce0 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
10cf0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
10d00 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
10d10 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
10d20 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10d30 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
10d40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10d50 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
10d60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
10d70 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
10d80 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
10d90 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
10da0 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
10db0 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
10dc0 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
10dd0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
10de0 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
10df0 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
10e00 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
10e10 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
10e20 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
10e30 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
10e40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10e50 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
10e60 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
10e70 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
10e80 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
10e90 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
10ea0 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
10eb0 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
10ec0 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
10ed0 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
10ee0 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
10ef0 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
10f00 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
10f10 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
10f20 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
10f30 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
10f40 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
10f50 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
10f60 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
10f70 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
10f80 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
10f90 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
10fa0 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
10fb0 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
10fc0 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
10fd0 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
10fe0 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
10ff0 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
11000 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
11010 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
11020 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
11030 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
11040 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
11050 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
11060 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
11070 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
11080 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
11090 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
110a0 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c  alloc, xRealloc,
110b0 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
110c0 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
110d0 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
110e0 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
110f0 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
11100 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
11110 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
11120 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
11130 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
11140 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
11150 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
11160 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
11170 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
11180 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
11190 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  dup..**.** xSize
111a0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
111b0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
111c0 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
111d0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
111e0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
111f0 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
11200 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
11210 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
11220 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
11230 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
11240 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
11250 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
11260 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
11270 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
11280 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
11290 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
112a0 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
112b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
112c0 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
112d0 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
112e0 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
112f0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
11300 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
11310 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
11320 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
11330 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
11340 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
11350 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
11360 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
11370 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
11380 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
11390 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
113a0 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
113b0 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
113c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
113d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
113e0 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
113f0 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
11400 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
11410 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
11420 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
11430 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
11440 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
11450 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
11460 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
11470 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
11480 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20  allocator.  For 
11490 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
114a0 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
114b0 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
114c0 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
114d0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
114e0 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
114f0 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
11500 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
11510 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
11520 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
11530 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
11540 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
11550 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
11560 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
11570 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
11580 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
11590 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
115a0 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
115b0 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
115c0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
115d0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
115e0 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
115f0 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
11600 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
11610 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
11620 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
11630 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
11640 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
11650 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
11660 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
11670 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
11680 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
11690 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
116a0 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
116b0 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
116c0 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
116d0 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
116e0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
116f0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
11700 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
11710 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
11720 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11730 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
11740 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
11750 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
11760 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
11770 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
11780 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
11790 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
117a0 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
117b0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
117c0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
117d0 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
117e0 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
117f0 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
11800 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
11810 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
11820 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
11830 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
11840 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
11850 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
11860 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
11870 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
11880 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
11890 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
118a0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
118b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
118c0 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
118d0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
118e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
118f0 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
11900 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
11910 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
11920 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
11930 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
11940 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
11950 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
11960 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
11970 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
11980 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
11990 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
119a0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
119b0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
119c0 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
119d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
119e0 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
119f0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
11a00 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
11a10 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
11a20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
11a30 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
11a40 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
11a50 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
11a60 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
11a70 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
11a80 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
11a90 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
11aa0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
11ab0 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
11ac0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
11ad0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
11ae0 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
11af0 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
11b00 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
11b10 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
11b20 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
11b30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11b40 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
11b50 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
11b60 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
11b70 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
11b80 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
11b90 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
11ba0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
11bb0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
11bc0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
11bd0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
11be0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
11bf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
11c00 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11c10 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
11c20 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11c30 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
11c40 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
11c50 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
11c60 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
11c70 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
11c80 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
11c90 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
11ca0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
11cb0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
11cc0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
11cd0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
11ce0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
11cf0 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
11d00 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
11d10 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
11d20 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
11d30 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
11d40 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
11d50 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
11d60 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
11d70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11d80 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
11d90 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
11da0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
11db0 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
11dc0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
11dd0 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
11de0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
11df0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
11e00 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
11e10 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
11e20 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
11e30 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
11e40 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
11e50 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
11e60 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
11e70 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
11e80 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
11e90 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
11ea0 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
11eb0 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
11ec0 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
11ed0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11ee0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
11ef0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
11f00 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11f10 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
11f20 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
11f30 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
11f40 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
11f50 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
11f60 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
11f70 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
11f80 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
11f90 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
11fa0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
11fb0 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
11fc0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
11fd0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
11fe0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
11ff0 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
12000 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
12010 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12020 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
12030 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
12040 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
12050 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
12060 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
12070 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
12080 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
12090 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
120a0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
120b0 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
120c0 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
120d0 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
120e0 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
120f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12100 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
12110 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
12120 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
12130 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
12140 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
12150 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
12160 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
12170 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
12180 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
12190 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
121a0 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
121b0 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
121c0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
121d0 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
121e0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
121f0 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
12200 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
12210 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
12220 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
12230 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
12240 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
12250 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
12260 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12270 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12280 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12290 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
122a0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
122b0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
122c0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
122d0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
122e0 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
122f0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
12300 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
12310 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12320 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
12330 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
12340 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
12350 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
12360 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
12370 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
12380 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12390 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
123a0 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
123b0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
123c0 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
123d0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
123e0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
123f0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
12400 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
12410 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12420 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
12430 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12440 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
12450 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
12460 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
12470 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
12480 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
12490 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
124a0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
124b0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
124c0 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
124d0 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
124e0 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
124f0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12500 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
12510 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
12520 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
12530 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
12540 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
12550 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
12560 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
12570 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
12580 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
12590 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
125a0 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
125b0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
125c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
125d0 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
125e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
125f0 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
12600 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
12610 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
12620 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12630 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12640 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12650 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12660 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12670 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12680 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
12690 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
126a0 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
126b0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
126c0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
126d0 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
126e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
126f0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
12700 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
12710 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
12720 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
12730 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
12740 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12750 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
12760 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12770 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
12780 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
12790 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f  _CONFIG_MALLOC o
127a0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
127b0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
127c0 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
127d0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
127e0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
127f0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12800 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
12810 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
12820 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
12830 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
12840 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12850 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
12860 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
12870 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
12880 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
12890 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
128a0 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
128b0 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
128c0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
128d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
128e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
128f0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
12900 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
12910 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
12920 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
12930 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
12940 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12950 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
12960 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
12970 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
12980 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
12990 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
129a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
129b0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
129c0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
129d0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
129e0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
129f0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12a00 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
12a10 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
12a20 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
12a30 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
12a40 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
12a50 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
12a60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12a70 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
12a80 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
12a90 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
12aa0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
12ab0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
12ac0 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
12ad0 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
12ae0 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
12af0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
12b00 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
12b10 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
12b20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
12b30 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12b40 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
12b50 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
12b60 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
12b70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
12b80 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12b90 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f  _MEMSTATUS optio
12ba0 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
12bb0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
12bc0 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65  int,.** interpre
12bd0 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
12be0 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
12bf0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
12c00 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a  collection of.**
12c10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12c20 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  on statistics. ^
12c30 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
12c40 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
12c50 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  cs are.** disabl
12c60 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ed, the followin
12c70 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
12c80 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
12c90 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
12ca0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
12cb0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
12cc0 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
12cd0 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12ce0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
12cf0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12d00 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
12d10 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
12d20 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
12d30 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  64()].**   </ul>
12d40 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
12d50 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
12d60 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
12d70 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
12d80 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
12d90 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
12da0 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
12db0 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
12dc0 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
12dd0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
12de0 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
12df0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
12e00 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
12e10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12e20 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51  SCRATCH]] <dt>SQ
12e30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
12e40 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
12e50 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
12e60 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69  FIG_SCRATCH opti
12e70 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
12e80 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
12e90 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  fer.** that SQLi
12ea0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73  te can use for s
12eb0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
12ec0 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65  ^(There are thre
12ed0 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74  e arguments.** t
12ee0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
12ef0 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e  SCRATCH:  A poin
12f00 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
12f10 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
12f20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
12f30 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
12f40 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
12f50 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
12f60 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
12f70 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
12f80 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
12f90 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
12fa0 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
12fb0 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a  ations (N).)^.**
12fc0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12fd0 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
12fe0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
12ff0 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
13000 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
13010 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
13020 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
13030 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d  e will not use m
13040 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72  ore than one scr
13050 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
13060 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c   thread..** ^SQL
13070 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72  ite will never r
13080 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68  equest a scratch
13090 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20   buffer that is 
130a0 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74  more than 6.** t
130b0 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
130c0 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20  e page size..** 
130d0 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
130e0 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
130f0 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
13100 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
13110 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
13120 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
13130 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
13140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
13150 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
13160 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
13170 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
13180 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  p>.** ^When the 
13190 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76  application prov
131a0 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20  ides any amount 
131b0 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  of scratch memor
131c0 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54  y using.** SQLIT
131d0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
131e0 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20  , SQLite avoids 
131f0 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67  unnecessary larg
13200 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
13210 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61  lloc|heap alloca
13220 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20  tions]..** This 
13230 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e  can help [Robson
13240 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d   proof|prevent m
13250 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13260 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74   failures] due t
13270 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65  o heap.** fragme
13280 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d  ntation in low-m
13290 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73  emory embedded s
132a0 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  ystems..** </dd>
132b0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
132c0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
132d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
132e0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
132f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13300 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
13310 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20  AGECACHE option 
13320 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
13330 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
13340 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
13350 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20  can use for the 
13360 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
13370 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
13380 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63  ault page.** cac
13390 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
133a0 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
133b0 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
133c0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
133d0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
133e0 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
133f0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
13400 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
13410 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
13420 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 0a  CONFIG_PCACHE2].
13430 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
13440 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65   option..** ^The
13450 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
13460 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
13470 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
13480 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a  E: A pointer to.
13490 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  ** 8-byte aligne
134a0 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  d.** memory, the
134b0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
134c0 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
134d0 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
134e0 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
134f0 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
13500 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
13510 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
13520 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
13530 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
13540 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
13550 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73  nd 65536) plus s
13560 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20  ome extra bytes 
13570 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
13580 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e   header.  ^The n
13590 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62  umber of extra b
135a0 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74  ytes needed by t
135b0 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a  he page header.*
135c0 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
135d0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53  ned using the [S
135e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
135f0 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f  CHE_HDRSZ] optio
13600 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  n .** to [sqlite
13610 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20  3_config()]..** 
13620 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
13630 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
13640 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
13650 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72  * for the sz par
13660 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72  ameter to be lar
13670 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61  ger than necessa
13680 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ry.  The first.*
13690 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
136a0 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  d pointer to an 
136b0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
136c0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74  lock of memory t
136d0 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61  hat.** is at lea
136e0 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
136f0 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69   memory, otherwi
13700 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  se subsequent be
13710 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
13720 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69  efined..** ^SQLi
13730 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
13740 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
13750 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
13760 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
13770 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
13780 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
13790 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
137a0 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
137b0 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
137c0 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
137d0 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
137e0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
137f0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
13800 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
13810 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
13820 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13830 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
13840 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
13850 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ace.</dd>.**.** 
13860 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13870 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
13880 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
13890 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
138a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
138b0 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  AP option specif
138c0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
138d0 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74  ory buffer .** t
138e0 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
138f0 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
13900 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
13910 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
13920 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f  ds.** beyond tho
13930 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  se provided for 
13940 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
13950 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a  G_SCRATCH] and.*
13960 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
13970 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
13980 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
13990 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69  IG_HEAP option i
139a0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
139b0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
139c0 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65  mpiled.** with e
139d0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
139e0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
139f0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
13a00 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74  MEMSYS5] and ret
13a10 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
13a20 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65  ERROR] if invoke
13a30 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20  d otherwise..** 
13a40 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
13a50 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
13a60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
13a70 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61  :.** An 8-byte a
13a80 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
13a90 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
13aa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
13ab0 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
13ac0 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
13ad0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
13ae0 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
13af0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
13b00 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
13b10 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
13b20 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
13b30 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
13b40 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
13b50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
13b60 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
13b70 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
13b80 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
13b90 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
13ba0 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
13bb0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
13bc0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
13bd0 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
13be0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  ot NULL then the
13bf0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
13c00 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
13c10 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
13c20 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
13c30 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
13c40 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
13c50 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
13c60 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
13c70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
13c80 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
13c90 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
13ca0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
13cb0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
13cc0 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
13cd0 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
13ce0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13cf0 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
13d00 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
13d10 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
13d20 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
13d30 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
13d40 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
13d50 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
13d60 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13d70 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
13d80 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
13d90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13da0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13db0 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
13dc0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13dd0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a  ment which is a.
13de0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
13df0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13e00 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13e10 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13e20 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
13e30 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c  ent specifies al
13e40 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
13e50 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
13e60 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a  es to be used.**
13e70 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75   in place the mu
13e80 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
13e90 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
13ea0 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
13eb0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
13ec0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
13ed0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13ee0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13ef0 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
13f00 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
13f10 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
13f20 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
13f30 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13f40 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13f50 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13f60 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13f70 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
13f80 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
13f90 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
13fa0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
13fb0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
13fc0 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
13fd0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
13fe0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13ff0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
14000 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
14010 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14020 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
14030 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
14040 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14050 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14060 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
14070 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14080 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
14090 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
140a0 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f  G_GETMUTEX optio
140b0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
140c0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
140d0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
140e0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
140f0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
14100 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
14110 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
14120 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
14130 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
14140 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
14150 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
14160 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
14170 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
14180 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
14190 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
141a0 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
141b0 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
141c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
141d0 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
141e0 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
141f0 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
14200 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
14210 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
14220 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
14230 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14240 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
14250 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
14260 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
14270 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
14280 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
14290 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
142a0 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
142b0 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
142c0 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
142d0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
142e0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
142f0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
14300 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14310 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
14320 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
14330 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
14340 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
14350 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14360 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14370 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14380 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
14390 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
143a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
143b0 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e  LOOKASIDE option
143c0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
143d0 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
143e0 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75  ine.** the defau
143f0 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61  lt size of looka
14400 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65  side memory on e
14410 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ach [database co
14420 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
14430 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14440 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
14450 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
14460 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
14470 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
14480 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
14490 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
144a0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
144b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
144c0 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   ^(SQLITE_CONFIG
144d0 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65  _LOOKASIDE.** se
144e0 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c  ts the <i>defaul
144f0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
14500 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
14510 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
14520 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20  SIDE].** option 
14530 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
14540 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
14550 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
14560 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
14570 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
14580 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
14590 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
145a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
145b0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
145c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
145d0 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
145e0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
145f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14600 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
14610 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14620 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
14630 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14640 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
14650 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
14660 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
14670 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
14680 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63  interface to a c
14690 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
146a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
146b0 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61  )^.** ^SQLite ma
146c0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
146d0 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  e [sqlite3_pcach
146e0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
146f0 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ct.</dd>.**.** [
14700 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
14710 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
14720 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14730 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
14740 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
14750 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14760 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
14770 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14780 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
14790 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
147a0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
147b0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
147c0 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
147d0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65   of.** the curre
147e0 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  nt page cache im
147f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
14800 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
14810 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14820 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14830 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14840 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
14850 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
14860 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
14870 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
14880 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
14890 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
148a0 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
148b0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
148c0 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
148d0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
148e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
148f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
14900 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
14910 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
14920 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
14930 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
14940 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
14950 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
14960 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
14970 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
14980 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
14990 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
149a0 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
149b0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
149c0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
149d0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
149e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
149f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
14a00 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
14a10 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
14a20 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
14a30 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
14a40 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
14a50 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
14a60 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
14a70 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
14a80 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
14a90 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
14aa0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
14ab0 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
14ac0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
14ad0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
14ae0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
14af0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
14b00 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
14b10 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
14b20 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
14b30 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
14b40 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
14b50 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
14b60 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
14b70 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
14b80 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
14b90 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
14ba0 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
14bb0 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
14bc0 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
14bd0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
14be0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
14bf0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
14c00 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
14c10 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
14c20 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
14c30 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
14c40 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
14c50 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
14c60 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
14c70 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
14c80 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
14c90 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
14ca0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
14cb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
14cc0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
14cd0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
14ce0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
14cf0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14d00 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
14d10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14d20 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68  _URI.** <dd>^(Th
14d30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14d40 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  URI option takes
14d50 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14d60 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a  nt of type int..
14d70 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  ** If non-zero, 
14d80 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
14d90 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
14da0 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
14db0 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
14dc0 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e  .** then URI han
14dd0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
14de0 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49  y disabled.)^ ^I
14df0 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
14e00 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e  s globally.** en
14e10 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
14e20 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b  ames passed to [
14e30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
14e40 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
14e50 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
14e60 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
14e70 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
14e80 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
14e90 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
14ea0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
14eb0 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
14ec0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
14ed0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
14ee0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
14ef0 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
14f00 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
14f10 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14f20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
14f30 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
14f40 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
14f50 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
14f60 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
14f70 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
14f80 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
14f90 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
14fa0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
14fb0 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
14fc0 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
14fd0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
14fe0 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
14ff0 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
15000 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
15010 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
15020 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
15030 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
15040 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
15050 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
15060 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
15070 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15080 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
15090 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
150a0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
150b0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
150c0 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SCAN option take
150d0 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
150e0 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77  er.** argument w
150f0 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
15100 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
15110 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
15120 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a  ble or disable.*
15130 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  * the use of cov
15140 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
15150 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
15160 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
15170 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54  optimizer..** ^T
15180 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
15190 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
151a0 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
151b0 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
151c0 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
151d0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
151e0 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
151f0 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
15200 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
15210 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
15220 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
15230 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
15240 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
15250 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
15260 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
15270 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
15280 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
15290 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
152a0 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
152b0 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  * when the optim
152c0 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
152d0 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
152e0 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
152f0 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
15300 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
15310 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
15320 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
15330 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
15340 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
15350 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
15360 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
15370 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15380 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
15390 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
153a0 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
153b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
153c0 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
153d0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
153e0 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
153f0 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
15400 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
15410 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
15420 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
15430 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
15440 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
15450 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
15460 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
15470 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
15480 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
15490 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
154a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
154b0 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
154c0 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
154d0 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
154e0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
154f0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
15500 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
15510 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
15520 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
15530 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15540 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
15550 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
15560 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
15570 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
15580 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
15590 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
155a0 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
155b0 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
155c0 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
155d0 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
155e0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
155f0 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
15600 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
15610 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
15620 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
15630 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
15640 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
15650 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
15660 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
15670 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15680 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
15690 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
156a0 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
156b0 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
156c0 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
156d0 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
156e0 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
156f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
15700 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
15710 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
15720 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15730 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
15740 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
15750 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
15760 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
15770 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
15780 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
15790 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
157a0 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
157b0 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
157c0 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
157d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
157e0 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
157f0 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
15800 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
15810 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
15820 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
15830 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
15840 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
15850 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
15860 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
15870 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
15880 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
15890 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
158a0 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
158b0 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
158c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
158d0 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
158e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
158f0 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
15900 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  >^SQLITE_CONFIG_
15910 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
15920 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
15930 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
15940 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
15950 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
15960 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
15970 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
15980 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
15990 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
159a0 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
159b0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
159c0 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  ize limit..** ^T
159d0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
159e0 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  ng can be overri
159f0 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74  dden by each dat
15a00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15a10 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72   using.** either
15a20 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61   the [PRAGMA mma
15a30 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c  p_size] command,
15a40 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65   or by using the
15a50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
15a60 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
15a70 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68  e control.  ^(Th
15a80 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
15a90 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77  d mmap size.** w
15aa0 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20  ill be silently 
15ab0 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63  truncated if nec
15ac0 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69  essary so that i
15ad0 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65  t does not excee
15ae0 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d the.** compile
15af0 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
15b00 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
15b10 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
15b20 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
15b30 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15b40 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
15b50 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
15b60 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
15b70 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
15b80 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
15b90 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
15ba0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
15bb0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ult..**.** [[SQL
15bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15bd0 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  _HEAPSIZE]].** <
15be0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15bf0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a  _WIN32_HEAPSIZE.
15c00 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15c10 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15c20 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20  HEAPSIZE option 
15c30 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
15c40 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a  e if SQLite is.*
15c50 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57  * compiled for W
15c60 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20  indows with the 
15c70 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41  [SQLITE_WIN32_MA
15c80 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOC] pre-proces
15c90 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66  sor macro.** def
15ca0 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f  ined. ^SQLITE_CO
15cb0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15cc0 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62  IZE takes a 32-b
15cd0 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
15ce0 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61  ger value.** tha
15cf0 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
15d00 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
15d10 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70  the created heap
15d20 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15d30 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
15d40 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  DRSZ]].** <dt>SQ
15d50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15d60 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e  HE_HDRSZ.** <dd>
15d70 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15d80 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
15d90 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15da0 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
15db0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
15dc0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
15dd0 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69  ger and writes i
15de0 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
15df0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
15e00 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65  xtra.** bytes pe
15e10 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20  r page required 
15e20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e  for each page in
15e30 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
15e40 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
15e50 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74  he amount of ext
15e60 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65  ra space require
15e70 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70  d can change dep
15e80 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
15e90 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65  mpiler,.** targe
15ea0 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20  t platform, and 
15eb0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a  SQLite version..
15ec0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15ed0 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a  ONFIG_PMASZ]].**
15ee0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15ef0 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e  IG_PMASZ.** <dd>
15f00 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15f10 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20  IG_PMASZ option 
15f20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
15f30 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
15f40 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  * is an unsigned
15f50 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74   integer and set
15f60 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50  s the "Minimum P
15f70 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65  MA Size" for the
15f80 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a   multithreaded.*
15f90 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74  * sorter to that
15fa0 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64   integer.  The d
15fb0 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50  efault minimum P
15fc0 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62  MA Size is set b
15fd0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
15fe0 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63  _SORTER_PMASZ] c
15ff0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16000 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73  on.  New threads
16010 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a   are launched.**
16020 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f   to help with so
16030 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68  rt operations wh
16040 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  en multithreaded
16050 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65   sorting.** is e
16060 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68  nabled (using th
16070 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64  e [PRAGMA thread
16080 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20  s] command) and 
16090 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  the amount of co
160a0 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73  ntent.** to be s
160b0 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68  orted exceeds th
160c0 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65  e page size time
160d0 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66  s the minimum of
160e0 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   the.** [PRAGMA 
160f0 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74  cache_size] sett
16100 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c  ing and this val
16110 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ue..** </dl>.*/.
16120 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16130 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
16140 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
16150 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16160 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
16170 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
16180 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16190 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
161a0 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
161b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
161c0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
161d0 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
161e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
161f0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16200 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
16210 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
16220 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
16230 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
16250 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
16260 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
16270 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
16280 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16290 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
162a0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
162b0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
162c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
162d0 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
162e0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
162f0 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
16300 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16310 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
16320 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
16330 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
16340 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
16350 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
16360 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
16370 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
16380 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16390 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
163a0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
163b0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
163c0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
163d0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
163e0 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
163f0 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
16400 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
16410 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
16420 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
16430 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16450 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
16460 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
16470 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16480 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
16490 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
164a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
164b0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
164c0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
164d0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
164e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
164f0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
16500 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16510 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16520 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
16530 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
16540 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
16550 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16560 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
16570 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
16580 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
16590 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
165a0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
165b0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
165c0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
165d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
165e0 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
165f0 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
16600 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
16610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
16620 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
16630 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
16640 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
16650 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16660 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
16670 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20  APSIZE      23  
16680 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
16690 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
166a0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
166b0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a  SZ        24  /*
166c0 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65   int *psz */.#de
166d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
166e0 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20  IG_PMASZ        
166f0 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e         25  /* un
16700 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61  signed int szPma
16710 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
16720 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
16730 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
16740 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
16750 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
16760 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
16770 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
16780 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16790 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
167a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
167b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
167c0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
167d0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
167e0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
167f0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
16800 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
16810 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
16820 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
16830 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
16840 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16850 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
16860 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
16870 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
16880 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
16890 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
168a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
168b0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
168c0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
168d0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
168e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
168f0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
16900 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
16910 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
16920 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
16930 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
16940 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
16950 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
16960 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
16970 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
16980 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
16990 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
169a0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
169b0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
169c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
169d0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
169e0 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
169f0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
16a00 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
16a10 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
16a20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
16a30 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
16a40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
16a50 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
16a60 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
16a70 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
16a80 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
16a90 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
16aa0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
16ab0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
16ac0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
16ad0 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
16ae0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
16af0 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
16b00 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
16b10 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
16b20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
16b30 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
16b40 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
16b50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
16b60 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
16b70 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
16b80 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
16b90 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
16ba0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
16bb0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
16bc0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
16bd0 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
16be0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
16bf0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
16c00 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
16c10 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
16c20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
16c30 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
16c40 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
16c50 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
16c60 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
16c70 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
16c80 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
16c90 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
16ca0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
16cb0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16cc0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
16cd0 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
16ce0 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
16cf0 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
16d00 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
16d10 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
16d20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
16d30 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
16d40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
16d50 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
16d60 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
16d70 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
16d80 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
16d90 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
16da0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
16db0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
16dc0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
16dd0 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
16de0 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
16df0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
16e00 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
16e10 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
16e20 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
16e30 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
16e40 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
16e50 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
16e60 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
16e70 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
16e80 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
16e90 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
16ea0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
16eb0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
16ec0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
16ed0 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
16ee0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
16ef0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
16f00 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
16f10 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
16f20 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
16f30 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
16f40 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
16f50 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
16f60 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
16f70 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
16f80 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
16f90 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
16fa0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16fb0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
16fc0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
16fd0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
16fe0 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
16ff0 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
17000 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
17010 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
17020 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
17030 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
17040 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17050 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17060 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
17070 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
17080 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
17090 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
170a0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
170b0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
170c0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
170d0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
170e0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
170f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
17100 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
17110 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
17120 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
17130 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
17140 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
17150 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17160 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
17170 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
17180 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
17190 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
171a0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
171b0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
171c0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
171d0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
171e0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
171f0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
17200 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
17210 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
17220 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
17230 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
17240 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
17250 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
17260 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
17270 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
17280 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
17290 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
172a0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
172b0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
172c0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
172d0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
172e0 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
172f0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
17300 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
17310 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
17320 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17330 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
17340 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
17350 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
17360 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
17370 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
17380 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
17390 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
173a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
173b0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
173c0 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20         1001  /* 
173d0 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
173e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
173f0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
17400 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f  FKEY     1002  /
17410 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
17420 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
17430 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
17440 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69  GGER  1003  /* i
17450 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
17460 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
17470 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
17480 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
17490 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  odes.** METHOD: 
174a0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
174b0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
174c0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
174d0 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
174e0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
174f0 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
17500 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
17510 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
17520 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
17530 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
17540 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
17550 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
17560 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
17570 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ity..*/.SQLITE_A
17580 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
17590 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78  DCALL sqlite3_ex
175a0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
175b0 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
175c0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
175d0 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
175e0 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20  Insert Rowid.** 
175f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
17600 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
17610 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65  y in most SQLite
17620 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20   tables (except 
17630 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  for [WITHOUT ROW
17640 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68  ID] tables).** h
17650 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
17660 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
17670 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
17680 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
17690 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
176a0 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
176b0 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
176c0 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
176d0 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
176e0 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
176f0 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
17700 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
17710 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
17720 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
17730 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
17740 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
17750 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
17760 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
17770 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
17780 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
17790 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
177a0 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
177b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73  ^The sqlite3_las
177c0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
177d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
177e0 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
177f0 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20  of the .** most 
17800 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
17810 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
17820 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72  a rowid table or
17830 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
17840 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20  .** on database 
17850 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a  connection D..**
17860 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b   ^Inserts into [
17870 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
17880 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65  ables are not re
17890 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e  corded..** ^If n
178a0 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
178b0 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69  SERT]s into rowi
178c0 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65  d tables.** have
178d0 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
178e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
178f0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a  onnection D, .**
17900 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61   then sqlite3_la
17910 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17920 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  D) returns zero.
17930 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
17940 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
17950 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
17960 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
17970 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
17980 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
17990 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
179a0 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
179b0 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
179c0 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
179d0 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
179e0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
179f0 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
17a00 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
17a10 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
17a20 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
17a30 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
17a40 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
17a50 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
17a60 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
17a70 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
17a80 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
17a90 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
17aa0 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
17ab0 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
17ac0 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
17ad0 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
17ae0 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
17af0 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
17b00 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
17b10 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
17b20 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
17b30 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
17b40 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
17b50 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
17b60 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
17b70 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
17b80 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
17b90 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
17ba0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
17bb0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
17bc0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
17bd0 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
17be0 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
17bf0 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
17c00 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
17c10 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
17c20 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
17c30 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
17c40 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
17c50 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
17c60 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
17c70 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
17c80 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
17c90 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
17ca0 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
17cb0 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
17cc0 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
17cd0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
17ce0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
17cf0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
17d00 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
17d10 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
17d20 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
17d30 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
17d40 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
17d50 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
17d60 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
17d70 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
17d80 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
17d90 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
17da0 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
17db0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17dc0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
17dd0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
17de0 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
17df0 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
17e00 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
17e10 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
17e20 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
17e30 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
17e40 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
17e50 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
17e60 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
17e70 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
17e80 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
17e90 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
17ea0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
17eb0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
17ec0 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
17ed0 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
17ee0 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
17ef0 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
17f00 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
17f10 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
17f20 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  owid]..*/.SQLITE
17f30 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
17f40 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  64 SQLITE_STDCAL
17f50 4c 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  L sqlite3_last_i
17f60 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
17f70 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
17f80 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
17f90 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
17fa0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
17fb0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
17fc0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
17fd0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
17fe0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
17ff0 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20  ified, inserted 
18000 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
18010 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
18020 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
18030 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
18040 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
18050 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  nt on the databa
18060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  se connection sp
18070 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
18080 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  nly parameter..*
18090 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  * ^Executing any
180a0 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
180b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
180c0 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  s not modify the
180d0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
180e0 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
180f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  ion..**.** ^Only
18100 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69   changes made di
18110 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e  rectly by the IN
18120 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
18130 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
18140 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
18150 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63  ed - auxiliary c
18160 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
18170 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
18180 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a   | triggers], .*
18190 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
181a0 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c  ctions] or [REPL
181b0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
181c0 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e  resolution are n
181d0 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
181e0 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
181f0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
18200 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a  tercepted by .**
18210 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
18220 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f  gger | INSTEAD O
18230 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20  F triggers] are 
18240 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68  not counted. ^Th
18250 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75  e value .** retu
18260 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
18270 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69  changes() immedi
18280 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49  ately after an I
18290 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
182a0 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74   .** DELETE stat
182b0 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76  ement run on a v
182c0 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65  iew is always ze
182d0 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ro. Only changes
182e0 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a   made to real .*
182f0 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75  * tables are cou
18300 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  nted..**.** Thin
18310 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70  gs are more comp
18320 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73  licated if the s
18330 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
18340 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
18350 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61  executed while a
18360 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
18370 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69   is running. Thi
18380 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20  s may happen if 
18390 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  the.** program u
183a0 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73  ses the [changes
183b0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
183c0 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68  , or if some oth
183d0 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  er callback.** f
183e0 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  unction invokes 
183f0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18400 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65  ) directly. Esse
18410 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20  ntially:.** .** 
18420 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  <ul>.**   <li> ^
18430 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67  (Before entering
18440 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
18450 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  am the value ret
18460 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
18470 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67     sqlite3_chang
18480 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
18490 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68   saved. After th
184a0 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
184b0 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73  m .**        has
184c0 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f   finished, the o
184d0 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73  riginal value is
184e0 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20   restored.)^.** 
184f0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74  .**   <li> ^(Wit
18500 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72  hin a trigger pr
18510 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52  ogram each INSER
18520 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45  T, UPDATE and DE
18530 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20  LETE .**        
18540 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74  statement sets t
18550 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
18560 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
18570 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
18580 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f    upon completio
18590 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20  n as normal. Of 
185a0 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c  course, this val
185b0 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c  ue will not incl
185c0 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61  ude .**        a
185d0 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f  ny changes perfo
185e0 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67  rmed by sub-trig
185f0 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c  gers, as the sql
18600 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
18610 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20  **        value 
18620 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e  will be saved an
18630 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72  d restored after
18640 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65   each sub-trigge
18650 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20  r has run.)^.** 
18660 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68  </ul>.** .** ^Th
18670 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
18680 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53   the changes() S
18690 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20  QL function (or 
186a0 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64  similar) is used
186b0 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
186c0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
186d0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
186e0 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
186f0 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74  gger, it .** ret
18700 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61  urns the value a
18710 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63  s set when the c
18720 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  alling statement
18730 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67   began executing
18740 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75  ..** ^If it is u
18750 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  sed by the secon
18760 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  d or subsequent 
18770 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77  such statement w
18780 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
18790 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65  .** program, the
187a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
187b0 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d  reflects the num
187c0 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
187d0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
187e0 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c  previous INSERT,
187f0 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
18800 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
18810 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  in the same trig
18820 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ger..**.** See a
18830 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
18840 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
18850 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
18860 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
18870 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
18880 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
18890 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
188a0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
188b0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
188c0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
188d0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
188e0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
188f0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
18900 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
18910 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
18920 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
18930 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
18940 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
18950 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
18960 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
18970 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18980 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
18990 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
189a0 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
189b0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
189c0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
189d0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
189e0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  n returns the to
189f0 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  tal number of ro
18a00 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64  ws inserted, mod
18a10 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  ified or.** dele
18a20 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45  ted by all [INSE
18a30 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72  RT], [UPDATE] or
18a40 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
18a50 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a  ents completed.*
18a60 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  * since the data
18a70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18a80 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c  was opened, incl
18a90 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63  uding those exec
18aa0 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  uted as.** part 
18ab0 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  of trigger progr
18ac0 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20  ams. ^Executing 
18ad0 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
18ae0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  f SQL statement.
18af0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65  ** does not affe
18b00 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ct the value ret
18b10 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
18b20 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
18b30 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65  ..** .** ^Change
18b40 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  s made as part o
18b50 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  f [foreign key a
18b60 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c  ctions] are incl
18b70 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63  uded in the.** c
18b80 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20  ount, but those 
18b90 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20  made as part of 
18ba0 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
18bb0 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
18bc0 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67  e.** not. ^Chang
18bd0 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
18be0 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
18bf0 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20  d by INSTEAD OF 
18c00 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65  triggers .** are
18c10 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   not counted..**
18c20 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68   .** See also th
18c30 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
18c40 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
18c50 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
18c60 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
18c70 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
18c80 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
18c90 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
18ca0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
18cb0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
18cc0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
18cd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18ce0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
18cf0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
18d00 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
18d10 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
18d20 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
18d30 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
18d40 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
18d50 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
18d60 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
18d70 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
18d80 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
18d90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18da0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
18db0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
18dc0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
18dd0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
18de0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
18df0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
18e00 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
18e10 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
18e20 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
18e30 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
18e40 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
18e50 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
18e60 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
18e70 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
18e80 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
18e90 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
18ea0 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
18eb0 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
18ec0 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
18ed0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
18ee0 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
18ef0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
18f00 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
18f10 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
18f20 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
18f30 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
18f40 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
18f50 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
18f60 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
18f70 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
18f80 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
18f90 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
18fa0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
18fb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
18fc0 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
18fd0 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
18fe0 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
18ff0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
19000 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
19010 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
19020 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
19030 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
19040 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
19050 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
19060 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
19070 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
19080 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
19090 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
190a0 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
190b0 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
190c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
190d0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
190e0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
190f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
19100 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
19110 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
19120 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
19130 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
19140 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
19150 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
19160 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
19170 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
19180 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
19190 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
191a0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
191b0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
191c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
191d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
191e0 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
191f0 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
19200 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
19210 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
19220 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
19230 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
19240 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
19250 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
19260 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
19270 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
19280 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
19290 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
192a0 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
192b0 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
192c0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
192d0 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
192e0 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
192f0 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
19300 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
19310 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
19320 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
19330 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
19340 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
19350 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
19360 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
19370 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
19380 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
19390 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
193a0 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
193b0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
193c0 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
193d0 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
193e0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
193f0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
19400 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
19410 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
19420 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
19430 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
19440 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
19450 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
19460 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
19470 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
19480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19490 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
194a0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
194b0 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
194c0 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
194d0 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
194e0 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  happen..*/.SQLIT
194f0 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
19500 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
19510 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
19520 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
19530 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
19540 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
19550 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
19560 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
19570 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
19580 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
19590 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
195a0 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
195b0 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
195c0 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
195d0 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
195e0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
195f0 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
19600 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
19610 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
19620 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
19630 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
19640 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
19650 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
19660 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
19670 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
19680 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
19690 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
196a0 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
196b0 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
196c0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
196d0 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
196e0 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
196f0 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
19700 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
19710 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
19720 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
19730 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
19740 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
19750 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
19760 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
19770 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
19780 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
19790 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
197a0 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
197b0 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
197c0 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
197d0 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
197e0 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
197f0 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
19800 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
19810 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
19820 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
19830 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
19840 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
19850 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
19860 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
19870 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
19880 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
19890 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
198a0 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
198b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
198c0 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
198d0 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
198e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
198f0 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
19900 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
19910 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
19920 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
19930 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
19940 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
19950 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
19960 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
19970 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
19980 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
19990 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
199a0 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
199b0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
199c0 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
199d0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
199e0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
199f0 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
19a00 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
19a10 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
19a20 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
19a30 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
19a40 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
19a50 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
19a60 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
19a70 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
19a80 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
19a90 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
19aa0 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
19ab0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
19ac0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
19ad0 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
19ae0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
19af0 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
19b00 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
19b10 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
19b20 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
19b30 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
19b40 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
19b50 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
19b60 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
19b70 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
19b80 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
19b90 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
19ba0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
19bb0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
19bc0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
19bd0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  L sqlite3_comple
19be0 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
19bf0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
19c00 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
19c10 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
19c20 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
19c30 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57  Y Errors.** KEYW
19c40 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64  ORDS: {busy-hand
19c50 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62  ler callback} {b
19c60 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20  usy handler}.** 
19c70 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
19c80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
19c90 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
19ca0 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73  D,X,P) routine s
19cb0 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
19cc0 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61  unction X.** tha
19cd0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
19ce0 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
19cf0 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61   P whenever.** a
19d00 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
19d10 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61  e to access a da
19d20 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73  tabase table ass
19d30 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
19d40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19d50 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f  tion] D when ano
19d60 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
19d70 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68  r process has th
19d80 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a  e table locked..
19d90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
19da0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e  usy_handler() in
19db0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
19dc0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20  to implement.** 
19dd0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
19de0 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52  meout()] and [PR
19df0 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
19e00 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  t]..**.** ^If th
19e10 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
19e20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
19e30 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69  QLITE_BUSY].** i
19e40 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
19e50 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
19e60 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
19e70 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
19e80 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
19e90 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
19ea0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
19eb0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
19ec0 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
19ed0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
19ee0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
19ef0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
19f00 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
19f10 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
19f20 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
19f30 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
19f40 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
19f50 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
19f60 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
19f70 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
19f80 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
19f90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
19fa0 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
19fb0 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
19fc0 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70  * been invoked p
19fd0 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68  reviously for th
19fe0 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65  e same locking e
19ff0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
1a000 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
1a010 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
1a020 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
1a030 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
1a040 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
1a050 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
1a060 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72  QLITE_BUSY] is r
1a070 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68  eturned.** to th
1a080 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a  e application..*
1a090 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
1a0a0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1a0b0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
1a0c0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
1a0d0 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74  made to access t
1a0e0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1a0f0 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
1a100 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
1a110 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
1a120 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
1a130 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
1a140 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
1a150 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
1a160 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
1a170 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
1a180 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
1a190 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
1a1a0 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
1a1b0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
1a1c0 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
1a1d0 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
1a1e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
1a1f0 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  Y].** to the app
1a200 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64  lication instead
1a210 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
1a220 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65   .** busy handle
1a230 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
1a240 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
1a250 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
1a260 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
1a270 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
1a280 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
1a290 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
1a2a0 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
1a2b0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
1a2c0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
1a2d0 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
1a2e0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
1a2f0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
1a300 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
1a310 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
1a320 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
1a330 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
1a340 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1a350 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
1a360 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
1a370 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
1a380 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1a390 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
1a3a0 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
1a3b0 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
1a3c0 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
1a3d0 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
1a3e0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
1a3f0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
1a400 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
1a410 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
1a420 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
1a430 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
1a440 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
1a450 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
1a460 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
1a470 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
1a480 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
1a490 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1a4a0 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
1a4b0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1a4c0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
1a4d0 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
1a4e0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1a4f0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1a500 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
1a510 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
1a520 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a530 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
1a540 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
1a550 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
1a560 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
1a570 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
1a580 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
1a590 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1a5a0 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75  t()].** or evalu
1a5b0 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75  ating [PRAGMA bu
1a5c0 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69  sy_timeout=N] wi
1a5d0 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  ll change the.**
1a5e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e   busy handler an
1a5f0 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79  d thus clear any
1a600 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1a610 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1a620 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
1a630 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
1a640 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
1a650 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
1a660 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
1a670 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1a680 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1a690 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68  handler.  In oth
1a6a0 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65  er words,.** the
1a6b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1a6c0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20   not reentrant. 
1a6d0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
1a6e0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
1a6f0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
1a700 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
1a710 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
1a720 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
1a730 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1a740 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
1a750 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1a760 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1a770 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c   handler..*/.SQL
1a780 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
1a790 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1a7a0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1a7b0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
1a7c0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
1a7d0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1a7e0 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
1a7f0 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48   Timeout.** METH
1a800 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1a810 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1a820 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
1a830 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
1a840 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
1a850 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
1a860 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
1a870 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
1a880 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
1a890 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
1a8a0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
1a8b0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
1a8c0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
1a8d0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1a8e0 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
1a8f0 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
1a900 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
1a910 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1a920 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
1a930 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
1a940 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
1a950 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
1a960 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
1a970 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
1a980 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
1a990 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
1a9a0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
1a9b0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
1a9c0 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
1a9d0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
1a9e0 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
1a9f0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1aa00 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1aa10 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
1aa20 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1aa30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1aa40 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65  ion] at any give
1aa50 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
1aa60 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1aa70 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
1aa80 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
1aa90 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1aaa0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
1aab0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
1aac0 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
1aad0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1aae0 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a   cleared.)^.**.*
1aaf0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52  * See also:  [PR
1ab00 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1ab10 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t].*/.SQLITE_API
1ab20 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1ab30 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79  ALL sqlite3_busy
1ab40 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1ab50 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1ab60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1ab70 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1ab80 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1ab90 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eries.** METHOD:
1aba0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
1abb0 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
1abc0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
1abd0 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
1abe0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1abf0 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
1ac00 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1ac10 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
1ac20 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
1ac30 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
1ac40 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
1ac50 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
1ac60 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
1ac70 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1ac80 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
1ac90 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
1aca0 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
1acb0 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
1acc0 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
1acd0 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
1ace0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
1acf0 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
1ad00 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
1ad10 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
1ad20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
1ad30 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
1ad40 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
1ad50 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1ad60 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
1ad70 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
1ad80 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
1ad90 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
1ada0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
1adb0 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
1adc0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1add0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
1ade0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
1adf0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
1ae00 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1ae10 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
1ae20 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
1ae30 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
1ae40 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
1ae50 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
1ae60 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
1ae70 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1ae80 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
1ae90 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
1aea0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
1aeb0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
1aec0 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
1aed0 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
1aee0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
1aef0 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
1af00 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
1af10 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
1af20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
1af30 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1af40 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
1af50 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
1af60 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1af70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1af80 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
1af90 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
1afa0 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
1afb0 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
1afc0 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
1afd0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
1afe0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
1aff0 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
1b000 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1b010 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1b020 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
1b030 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
1b040 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1b050 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
1b060 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
1b070 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1b080 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
1b090 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
1b0a0 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
1b0b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1b0c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1b0d0 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
1b0e0 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
1b0f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1b100 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
1b110 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
1b120 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
1b130 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
1b140 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
1b150 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
1b160 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1b170 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
1b180 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
1b190 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
1b1a0 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
1b1b0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
1b1c0 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
1b1d0 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
1b1e0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
1b1f0 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
1b200 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
1b210 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
1b220 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
1b230 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
1b240 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1b250 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b260 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
1b270 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1b280 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
1b290 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
1b2a0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
1b2b0 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
1b2c0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1b2d0 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
1b2e0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b2f0 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
1b300 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1b310 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
1b320 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b330 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
1b340 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
1b350 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
1b360 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
1b370 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1b380 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
1b390 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1b3a0 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
1b3b0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
1b3c0 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
1b3d0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
1b3e0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
1b3f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1b400 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
1b410 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
1b420 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
1b430 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
1b440 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
1b450 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
1b460 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1b470 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
1b480 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
1b490 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
1b4a0 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
1b4b0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
1b4c0 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
1b4d0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1b4e0 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
1b4f0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
1b500 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
1b510 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1b520 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
1b530 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
1b540 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
1b550 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1b560 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
1b570 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
1b580 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
1b590 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
1b5a0 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
1b5b0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
1b5c0 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
1b5d0 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
1b5e0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
1b5f0 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
1b600 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
1b610 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
1b620 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1b630 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1b640 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
1b650 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
1b660 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
1b670 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1b680 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
1b690 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
1b6a0 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
1b6b0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
1b6c0 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
1b6d0 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
1b6e0 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
1b6f0 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
1b700 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
1b710 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
1b720 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
1b730 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
1b740 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
1b750 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
1b760 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
1b770 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1b780 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
1b790 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
1b7a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1b7b0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1b7c0 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
1b7d0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
1b7e0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1b7f0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1b800 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1b810 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1b820 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
1b830 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
1b840 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1b850 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
1b860 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
1b870 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
1b880 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
1b890 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
1b8a0 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
1b8b0 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
1b8c0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1b8d0 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
1b8e0 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
1b8f0 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
1b900 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1b910 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
1b920 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
1b930 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
1b940 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
1b950 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1b960 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .);.SQLITE_API v
1b970 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
1b980 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  LL sqlite3_free_
1b990 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
1b9a0 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
1b9b0 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
1b9c0 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
1b9d0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1b9e0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1b9f0 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
1ba00 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
1ba10 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
1ba20 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
1ba30 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1ba40 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72  rary..** These r
1ba50 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61  outines understa
1ba60 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63  nd most of the c
1ba70 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74  ommon K&R format
1ba80 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a  ting options,.**
1ba90 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74   plus some addit
1baa0 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61  ional non-standa
1bab0 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61  rd formats, deta
1bac0 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e  iled below..** N
1bad0 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66  ote that some of
1bae0 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72   the more obscur
1baf0 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  e formatting opt
1bb00 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74  ions from recent
1bb10 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74  .** C-library st
1bb20 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74  andards are omit
1bb30 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d  ted from this im
1bb40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a  plementation..**
1bb50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1bb60 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
1bb70 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1bb80 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
1bb90 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
1bba0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
1bbb0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1bbc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
1bbd0 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1bbe0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1bbf0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1bc00 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1bc10 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1bc20 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1bc30 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1bc40 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1bc50 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1bc60 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
1bc70 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
1bc80 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
1bc90 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
1bca0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
1bcb0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1bcc0 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
1bcd0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
1bce0 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
1bcf0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1bd00 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
1bd10 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
1bd20 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
1bd30 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
1bd40 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1bd50 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
1bd60 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
1bd70 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
1bd80 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
1bd90 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
1bda0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
1bdb0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
1bdc0 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
1bdd0 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
1bde0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
1bdf0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
1be00 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
1be10 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
1be20 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
1be30 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
1be40 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
1be50 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
1be60 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
1be70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
1be80 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
1be90 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
1bea0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
1beb0 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
1bec0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
1bed0 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
1bee0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
1bef0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
1bf00 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
1bf10 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
1bf20 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
1bf30 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
1bf40 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
1bf50 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
1bf60 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
1bf70 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
1bf80 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
1bf90 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
1bfa0 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
1bfb0 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
1bfc0 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
1bfd0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1bfe0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
1bff0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
1c000 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
1c010 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
1c020 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
1c030 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
1c040 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
1c050 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
1c060 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
1c070 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1c080 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
1c090 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
1c0a0 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
1c0b0 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
1c0c0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
1c0d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c0e0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
1c0f0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
1c100 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
1c110 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1c120 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
1c130 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
1c140 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
1c150 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
1c160 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
1c170 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
1c180 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
1c190 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1c1a0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
1c1b0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
1c1c0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
1c1d0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
1c1e0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
1c1f0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22  re "%q", "%Q", "
1c200 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  %w" and "%z" opt
1c210 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
1c220 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
1c230 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
1c240 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
1c250 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
1c260 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
1c270 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
1c280 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
1c290 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
1c2a0 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
1c2b0 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
1c2c0 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
1c2d0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1c2e0 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
1c2f0 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
1c300 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
1c310 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
1c320 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
1c330 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
1c340 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
1c350 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
1c360 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
1c370 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
1c380 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
1c390 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
1c3a0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1c3b0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1c3c0 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
1c3d0 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
1c3e0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1c3f0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
1c400 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
1c410 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
1c420 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
1c430 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1c440 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1c450 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1c460 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1c470 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1c480 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
1c490 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1c4a0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1c4b0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1c4c0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1c4d0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1c4e0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1c4f0 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
1c500 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
1c510 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
1c520 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
1c530 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
1c540 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
1c550 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
1c560 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1c570 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1c580 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1c590 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
1c5a0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1c5b0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1c5c0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1c5d0 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
1c5e0 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
1c5f0 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
1c600 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
1c610 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
1c620 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
1c630 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1c640 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1c650 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1c660 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
1c670 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
1c680 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1c690 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
1c6a0 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
1c6b0 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
1c6c0 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
1c6d0 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
1c6e0 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
1c6f0 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
1c700 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
1c710 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
1c720 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
1c730 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
1c740 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
1c750 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
1c760 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
1c770 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
1c780 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1c790 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
1c7a0 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
1c7b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
1c7c0 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
1c7d0 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
1c7e0 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
1c7f0 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
1c800 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
1c810 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
1c820 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
1c830 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
1c840 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
1c850 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c860 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1c870 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1c880 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1c890 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
1c8a0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1c8b0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1c8c0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1c8d0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1c8e0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1c8f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1c900 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
1c910 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
1c920 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
1c930 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
1c940 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
1c950 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
1c960 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
1c970 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1c980 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d   ^(The "%w" form
1c990 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73  atting option is
1c9a0 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70   like "%q" excep
1c9b0 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74  t that it expect
1c9c0 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61  s to.** be conta
1c9d0 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62  ined within doub
1c9e0 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61  le-quotes instea
1c9f0 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74  d of single quot
1ca00 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73  es, and it.** es
1ca10 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65  capes the double
1ca20 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72  -quote character
1ca30 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1ca40 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20  single-quote.** 
1ca50 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68  character.)^  Th
1ca60 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e  e "%w" formattin
1ca70 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65  g option is inte
1ca80 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20  nded for safely 
1ca90 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62  inserting.** tab
1caa0 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61  le and column na
1cab0 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74  mes into a const
1cac0 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65  ructed SQL state
1cad0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ment..**.** ^(Th
1cae0 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
1caf0 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
1cb00 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
1cb10 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
1cb20 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
1cb30 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
1cb40 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
1cb50 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
1cb60 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
1cb70 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
1cb80 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
1cb90 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  ing.)^.*/.SQLITE
1cba0 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54  _API char *SQLIT
1cbb0 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f  E_CDECL sqlite3_
1cbc0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1cbd0 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  ar*,...);.SQLITE
1cbe0 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54  _API char *SQLIT
1cbf0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1cc00 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1cc10 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1cc20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1cc30 72 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20  r *SQLITE_CDECL 
1cc40 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1cc50 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1cc60 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51   char*, ...);.SQ
1cc70 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53  LITE_API char *S
1cc80 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1cc90 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1cca0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1ccb0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1ccc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ccd0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1cce0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1ccf0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1cd00 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1cd10 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1cd20 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1cd30 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1cd40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1cd50 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1cd60 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1cd70 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1cd80 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1cd90 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1cda0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1cdb0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1cdc0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1cdd0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1cde0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1cdf0 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1ce00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ce10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1ce20 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1ce30 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1ce40 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1ce50 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1ce60 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1ce70 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1ce80 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1ce90 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1cea0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1ceb0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1cec0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1ced0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1cee0 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1cef0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1cf00 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1cf10 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1cf20 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1cf30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1cf40 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1cf50 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
1cf60 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1cf70 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77  c64(N) routine w
1cf80 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a  orks just like.*
1cf90 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1cfa0 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  (N) except that 
1cfb0 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  N is an unsigned
1cfc0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1cfd0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1cfe0 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e  signed 32-bit in
1cff0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  teger..**.** ^Ca
1d000 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1d010 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1d020 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1d030 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1d040 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1d050 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1d060 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1d070 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1d080 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1d090 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1d0a0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1d0b0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1d0c0 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1d0d0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1d0e0 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1d0f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1d100 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1d110 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1d120 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1d130 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1d140 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1d150 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1d160 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1d170 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1d180 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1d190 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1d1a0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1d1b0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1d1c0 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1d1d0 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1d1e0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1d1f0 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1d200 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1d210 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1d220 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1d230 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1d240 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1d250 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1d260 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1d270 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1d280 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1d290 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1d2a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1d2b0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1d2c0 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1d2d0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1d2e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20  allocation X to 
1d2f0 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1d300 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
1d310 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  X parameter to s
1d320 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1d330 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ,N).** is a NULL
1d340 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1d350 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1d360 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1d370 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1d380 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20  lloc(N)..** ^If 
1d390 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
1d3a0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1d3b0 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20  oc(X,N) is zero 
1d3c0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1d3d0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1d3e0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1d3f0 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1d400 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1d410 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  X)..** ^sqlite3_
1d420 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1d430 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1d440 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1d450 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1d460 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1d470 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1d480 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
1d490 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ory is available
1d4a0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1d4b0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1d4c0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1d4d0 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1d4e0 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1d4f0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1d500 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1d510 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1d520 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1d530 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1d540 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74  alloc(X,N) and t
1d550 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1d560 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1d570 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1d580 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1d590 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
1d5a0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74  positive, then t
1d5b0 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f  he.** prior allo
1d5c0 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72  cation is not fr
1d5d0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1d5e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1d5f0 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  4(X,N) interface
1d600 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  s works the same
1d610 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   as.** sqlite3_r
1d620 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65  ealloc(X,N) exce
1d630 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36  pt that N is a 6
1d640 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  4-bit unsigned i
1d650 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1d660 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  * of a 32-bit si
1d670 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
1d680 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d  .** ^If X is a m
1d690 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d6a0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
1d6b0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1d6c0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  3_malloc(),.** s
1d6d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1d6e0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1d6f0 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  oc(), or sqlite3
1d700 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68  _realloc64(), th
1d710 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
1d720 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74  ize(X) returns t
1d730 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20  he size of that 
1d740 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d750 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  n in bytes..** ^
1d760 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1d770 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73  ed by sqlite3_ms
1d780 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20  ize(X) might be 
1d790 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
1d7a0 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
1d7b0 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65  es requested whe
1d7c0 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65  n X was allocate
1d7d0 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e  d.  ^If X is a N
1d7e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1d7f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1d800 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72  e(X) returns zer
1d810 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20  o.  If X points 
1d820 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61  to something tha
1d830 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20  t is not.** the 
1d840 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d  beginning of mem
1d850 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
1d860 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20  or if it points 
1d870 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a  to a formerly.**
1d880 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c   valid memory al
1d890 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61  location that ha
1d8a0 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64  s now been freed
1d8b0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
1d8c0 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ior.** of sqlite
1d8d0 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e  3_msize(X) is un
1d8e0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73  defined and poss
1d8f0 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ibly harmful..**
1d900 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1d910 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1d920 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71  te3_malloc(), sq
1d930 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1d940 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1d950 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69  oc64(), and sqli
1d960 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a  te3_realloc64().
1d970 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1d980 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1d990 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1d9a0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1d9b0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1d9c0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1d9d0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1d9e0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1d9f0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1da00 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1da10 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1da20 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1da30 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1da40 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1da50 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1da60 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1da70 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1da80 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1da90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1daa0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1dab0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1dac0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1dad0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1dae0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1daf0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1db00 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1db10 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1db20 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1db30 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1db40 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1db50 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1db60 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1db70 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1db80 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1db90 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1dba0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1dbb0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1dbc0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1dbd0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1dbe0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1dbf0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1dc00 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1dc10 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1dc20 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1dc30 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1dc40 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1dc50 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1dc60 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1dc70 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1dc80 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1dc90 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1dca0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1dcb0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1dcc0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1dcd0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1dce0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1dcf0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1dd00 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1dd10 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1dd20 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1dd30 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1dd40 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1dd50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1dd60 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1dd70 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1dd80 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1dd90 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1dda0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1ddb0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1ddc0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1ddd0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1dde0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1ddf0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1de00 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1de10 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1de20 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1de30 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  alloc()]..*/.SQL
1de40 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51  ITE_API void *SQ
1de50 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1de60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
1de70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1de80 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
1de90 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  L sqlite3_malloc
1dea0 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64(sqlite3_uint6
1deb0 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  4);.SQLITE_API v
1dec0 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
1ded0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ALL sqlite3_real
1dee0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1def0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1df00 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
1df10 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1df20 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
1df30 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  3_uint64);.SQLIT
1df40 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
1df50 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1df60 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53  3_free(void*);.S
1df70 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
1df80 33 5f 75 69 6e 74 36 34 20 53 51 4c 49 54 45 5f  3_uint64 SQLITE_
1df90 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1dfa0 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  msize(void*);../
1dfb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1dfc0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
1dfd0 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
1dfe0 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
1dff0 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
1e000 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
1e010 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
1e020 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
1e030 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
1e040 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1e050 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
1e060 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
1e070 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
1e080 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
1e090 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1e0a0 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
1e0b0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1e0c0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
1e0d0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1e0e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1e0f0 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
1e100 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
1e110 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
1e120 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
1e130 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1e140 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1e150 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
1e160 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
1e170 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
1e180 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1e190 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
1e1a0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1e1b0 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
1e1c0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
1e1d0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1e1e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1e1f0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1e200 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1e210 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
1e220 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
1e230 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
1e240 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
1e250 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1e260 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
1e270 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
1e280 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
1e290 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
1e2a0 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
1e2b0 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
1e2c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
1e2d0 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
1e2e0 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
1e2f0 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
1e300 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
1e310 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
1e320 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1e330 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
1e340 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
1e350 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
1e360 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1e370 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
1e380 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
1e390 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
1e3a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1e3b0 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
1e3c0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1e3d0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
1e3e0 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  reset..*/.SQLITE
1e3f0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
1e400 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  64 SQLITE_STDCAL
1e410 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  L sqlite3_memory
1e420 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c  _used(void);.SQL
1e430 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
1e440 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44  int64 SQLITE_STD
1e450 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d  CALL sqlite3_mem
1e460 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1e470 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1e480 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1e490 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1e4a0 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1e4b0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1e4c0 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1e4d0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1e4e0 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1e4f0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1e500 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1e510 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1e520 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1e530 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1e540 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1e550 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1e560 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1e570 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1e580 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1e590 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1e5a0 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1e5b0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1e5c0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1e5d0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1e5e0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1e5f0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1e600 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1e610 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1e620 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1e630 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1e640 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1e650 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1e660 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1e670 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74  * ^The P paramet
1e680 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c  er can be a NULL
1e690 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1e6a0 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
1e6b0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72   has not been pr
1e6c0 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20  eviously called 
1e6d0 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f  or if the previo
1e6e0 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e  us.** call had N
1e6f0 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f   less than one o
1e700 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
1e710 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65   for P, then the
1e720 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64   PRNG is.** seed
1e730 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
1e740 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ess obtained fro
1e750 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1e760 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74  s method of.** t
1e770 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1e780 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
1e790 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76  .** ^If the prev
1e7a0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
1e7b0 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e  s routine had an
1e7c0 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20   N of 1 or more 
1e7d0 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c  and a.** non-NUL
1e7e0 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65  L P then the pse
1e7f0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
1e800 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
1e810 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
1e820 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
1e830 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
1e840 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
1e850 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51  ** method..*/.SQ
1e860 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
1e870 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1e880 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
1e890 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
1e8a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e8b0 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
1e8c0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
1e8d0 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
1e8e0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1e8f0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1e900 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
1e910 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
1e920 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
1e930 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1e940 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
1e950 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
1e960 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
1e970 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e980 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1e990 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
1e9a0 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
1e9b0 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
1e9c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1e9d0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1e9e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e9f0 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
1ea00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1ea10 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1ea20 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
1ea30 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
1ea40 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
1ea50 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
1ea60 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
1ea70 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
1ea80 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
1ea90 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
1eaa0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1eab0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1eac0 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
1ead0 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
1eae0 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
1eaf0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1eb00 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
1eb10 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1eb20 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
1eb30 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
1eb40 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
1eb50 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
1eb60 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
1eb70 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
1eb80 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
1eb90 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
1eba0 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
1ebb0 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
1ebc0 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
1ebd0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
1ebe0 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
1ebf0 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
1ec00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ec10 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1ec20 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
1ec30 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
1ec40 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
1ec50 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
1ec60 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
1ec70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ec80 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1ec90 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1eca0 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
1ecb0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1ecc0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1ecd0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
1ece0 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1ecf0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1ed00 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
1ed10 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
1ed20 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
1ed30 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
1ed40 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1ed50 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
1ed60 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
1ed70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1ed80 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1ed90 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1eda0 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
1edb0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1edc0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1edd0 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
1ede0 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
1edf0 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
1ee00 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
1ee10 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1ee20 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ee30 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1ee40 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
1ee50 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
1ee60 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1ee70 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
1ee80 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1ee90 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
1eea0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1eeb0 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
1eec0 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
1eed0 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
1eee0 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
1eef0 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
1ef00 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
1ef10 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
1ef20 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
1ef30 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1ef40 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
1ef50 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1ef60 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
1ef70 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
1ef80 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
1ef90 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1efa0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
1efb0 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1efc0 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
1efd0 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
1efe0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1eff0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1f000 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1f010 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
1f020 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1f030 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
1f040 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
1f050 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1f060 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1f070 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1f080 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
1f090 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1f0a0 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
1f0b0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
1f0c0 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
1f0d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
1f0e0 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
1f0f0 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
1f100 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
1f110 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
1f120 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1f130 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1f140 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
1f150 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1f160 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
1f170 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
1f180 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
1f190 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
1f1a0 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
1f1b0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
1f1c0 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
1f1d0 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
1f1e0 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
1f1f0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
1f200 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
1f210 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1f220 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
1f230 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1f240 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
1f250 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
1f260 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
1f270 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1f280 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
1f290 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
1f2a0 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
1f2b0 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
1f2c0 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
1f2d0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
1f2e0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
1f2f0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
1f300 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
1f310 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
1f320 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
1f330 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
1f340 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
1f350 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
1f360 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
1f370 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
1f380 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
1f390 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
1f3a0 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
1f3b0 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
1f3c0 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
1f3d0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
1f3e0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
1f3f0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
1f400 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
1f410 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
1f420 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
1f430 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
1f440 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1f450 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
1f460 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
1f470 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
1f480 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
1f490 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1f4a0 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
1f4b0 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
1f4c0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
1f4d0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
1f4e0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
1f4f0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
1f500 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1f510 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
1f520 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
1f530 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
1f540 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1f550 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
1f560 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
1f570 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
1f580 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
1f590 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
1f5a0 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
1f5b0 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
1f5c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
1f5d0 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
1f5e0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1f5f0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
1f600 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
1f610 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
1f620 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
1f630 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
1f640 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
1f650 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
1f660 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
1f670 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1f680 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
1f690 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f6a0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1f6b0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1f6c0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1f6d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f6e0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1f6f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1f700 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
1f710 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1f720 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1f730 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f740 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1f750 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1f760 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1f770 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1f780 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1f790 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1f7a0 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
1f7b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
1f7c0 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
1f7d0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
1f7e0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
1f7f0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
1f800 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
1f810 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
1f820 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
1f830 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
1f840 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
1f850 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
1f860 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
1f870 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f880 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
1f890 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
1f8a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f8b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
1f8c0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
1f8d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1f8e0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
1f8f0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
1f900 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1f910 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
1f920 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
1f930 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
1f940 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
1f950 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
1f960 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
1f970 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
1f980 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
1f990 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
1f9a0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
1f9b0 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
1f9c0 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
1f9d0 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
1f9e0 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
1f9f0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
1fa00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
1fa10 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1fa20 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1fa30 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
1fa40 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
1fa50 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1fa60 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1fa70 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1fa80 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
1fa90 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
1faa0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fab0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
1fac0 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
1fad0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1fae0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1faf0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1fb00 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
1fb10 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
1fb20 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
1fb30 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
1fb40 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
1fb50 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
1fb60 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
1fb70 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
1fb80 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
1fb90 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
1fba0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1fbb0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1fbc0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
1fbd0 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
1fbe0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1fbf0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
1fc00 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
1fc10 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
1fc20 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c   [conflict resol
1fc30 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72  ution mode].** r
1fc40 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65  eturned from the
1fc50 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
1fc60 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
1fc70 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
1fc80 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
1fc90 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
1fca0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1fcb0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
1fcc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fcd0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
1fce0 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
1fcf0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
1fd00 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
1fd10 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1fd20 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
1fd30 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
1fd40 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1fd50 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
1fd60 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
1fd70 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
1fd80 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
1fd90 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
1fda0 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
1fdb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
1fdc0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
1fdd0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1fde0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1fdf0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
1fe00 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
1fe10 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
1fe20 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
1fe30 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
1fe40 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
1fe50 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
1fe60 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1fe70 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
1fe80 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
1fe90 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
1fea0 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
1feb0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
1fec0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
1fed0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
1fee0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
1fef0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1ff00 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
1ff10 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1ff20 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
1ff30 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
1ff40 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
1ff50 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
1ff60 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
1ff70 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1ff80 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
1ff90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1ffa0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1ffb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1ffc0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1ffd0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
1ffe0 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
1fff0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
20000 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
20010 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
20020 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
20030 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
20040 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
20050 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
20060 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
20070 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
20080 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
20090 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
200a0 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
200b0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
200c0 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
200d0 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
200e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
200f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20100 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
20110 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
20120 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
20130 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
20140 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
20150 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
20160 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
20170 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20180 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
20190 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
201a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
201b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
201c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
201d0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
201e0 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
201f0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
20200 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20210 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20220 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
20230 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
20240 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20250 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20260 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20270 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
20280 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
20290 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
202a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
202b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
202c0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
202d0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
202e0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
202f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20310 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
20320 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
20330 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
20340 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
20350 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
20360 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
20370 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
20380 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
20390 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
203a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
203b0 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
203c0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
203d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
203e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
203f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
20400 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
20410 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
20420 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
20430 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
20440 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
20450 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
20460 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
20470 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
20480 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20490 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
204a0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
204b0 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
204c0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
204d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
204e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
204f0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
20500 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
20510 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
20520 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20530 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
20540 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
20550 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
20560 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
20570 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20580 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
20590 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
205a0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
205b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
205c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
205d0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
205e0 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
205f0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
20600 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
20610 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20620 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
20630 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
20640 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
20650 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20660 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20670 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
20680 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
20690 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
206a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
206b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
206c0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
206d0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
206e0 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
206f0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
20700 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20710 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
20720 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
20730 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20740 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
20750 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20760 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
20770 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
20780 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
20790 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
207a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
207b0 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
207c0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
207d0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
207e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
207f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20800 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
20810 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
20820 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
20830 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
20840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
20850 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
20860 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
20870 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
20880 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
208a0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
208b0 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
208c0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
208d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
208e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
208f0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
20900 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
20910 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
20920 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
20930 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
20940 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
20950 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
20960 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
20970 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20980 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
20990 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
209a0 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
209b0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
209c0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
209d0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
209e0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
209f0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
20a00 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
20a10 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
20a20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
20a30 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
20a40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
20a50 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
20a60 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
20a70 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
20a80 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
20a90 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
20aa0 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
20ab0 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
20ac0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
20ad0 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
20ae0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
20af0 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
20b00 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
20b10 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
20b20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
20b30 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
20b40 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
20b50 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20  ITE_RECURSIVE   
20b60 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a           33   /*
20b70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20b80 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20b90 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
20ba0 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
20bb0 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
20bc0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
20bd0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
20be0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
20bf0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
20c00 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
20c10 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
20c20 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
20c30 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
20c40 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
20c50 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
20c60 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
20c70 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
20c80 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
20c90 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
20ca0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
20cb0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
20cc0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
20cd0 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
20ce0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
20cf0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
20d00 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
20d10 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
20d20 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
20d30 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
20d40 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
20d50 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
20d60 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
20d70 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
20d80 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
20d90 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
20da0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
20db0 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
20dc0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
20dd0 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
20de0 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
20df0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
20e00 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
20e10 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
20e20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
20e30 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
20e40 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
20e50 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
20e60 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
20e70 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
20e80 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
20e90 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
20ea0 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
20eb0 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
20ec0 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
20ed0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
20ee0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
20ef0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
20f00 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
20f10 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
20f20 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
20f30 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
20f40 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
20f50 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
20f60 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
20f70 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
20f80 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
20f90 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
20fa0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
20fb0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
20fc0 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
20fd0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
20fe0 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
20ff0 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
21000 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
21010 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
21020 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
21030 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
21040 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
21050 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
21060 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
21070 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
21080 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
21090 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
210a0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
210b0 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
210c0 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
210d0 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
210e0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
210f0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
21100 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
21110 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
21120 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
21130 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
21140 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
21150 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
21160 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
21170 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
21180 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72  DCALL sqlite3_tr
21190 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
211a0 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
211b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
211c0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
211d0 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49  PI SQLITE_EXPERI
211e0 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 53 51 4c  MENTAL void *SQL
211f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
21200 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
21210 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
21220 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
21230 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
21240 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
21250 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
21260 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
21270 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
21280 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
21290 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
212a0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
212b0 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
212c0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
212d0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
212e0 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
212f0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
21300 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
21310 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
21320 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
21330 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
21340 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
21350 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
21360 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
21370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
21380 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
21390 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
213a0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
213b0 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
213c0 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
213d0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
213e0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
213f0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
21400 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
21410 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
21420 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
21430 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
21440 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
21450 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
21460 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
21470 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
21480 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
21490 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
214a0 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
214b0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
214c0 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
214d0 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
214e0 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
214f0 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
21500 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
21510 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
21520 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
21530 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
21540 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
21550 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
21560 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
21570 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
21580 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
21590 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
215a0 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
215b0 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
215c0 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
215d0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
215e0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
215f0 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
21600 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
21610 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
21620 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
21630 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
21640 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
21650 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
21660 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
21670 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
21680 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
21690 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
216a0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
216b0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
216c0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
216d0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
216e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
216f0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
21700 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
21710 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
21720 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
21730 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21740 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
21750 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
21760 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
21770 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
21780 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
21790 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
217a0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
217b0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
217c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
217d0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
217e0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
217f0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
21800 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
21810 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
21820 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
21830 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
21840 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
21850 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
21860 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21870 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
21880 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
21890 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  on.** CONSTRUCTO
218a0 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
218b0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
218c0 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
218d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
218e0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
218f0 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  e .** filename a
21900 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
21910 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
21920 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
21930 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
21940 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
21950 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
21960 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
21970 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
21980 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
21990 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
219a0 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
219b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
219c0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
219d0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
219e0 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
219f0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
21a00 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
21a10 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
21a20 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
21a30 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
21a40 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
21a50 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
21a60 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
21a70 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
21a80 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
21a90 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
21aa0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
21ab0 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
21ac0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
21ad0 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
21ae0 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
21af0 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
21b00 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
21b10 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
21b20 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
21b30 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
21b40 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
21b50 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
21b60 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
21b70 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
21b80 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
21b90 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
21ba0 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
21bb0 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
21bc0 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
21bd0 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
21be0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
21bf0 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
21c00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
21c10 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c  ult encoding wil
21c20 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64  l be UTF-8 for d
21c30 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64  atabases created
21c40 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65   using.** sqlite
21c50 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
21c60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
21c70 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
21c80 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61  oding for databa
21c90 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75  ses.** created u
21ca0 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  sing sqlite3_ope
21cb0 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54  n16() will be UT
21cc0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
21cd0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
21ce0 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
21cf0 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
21d00 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
21d10 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
21d20 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
21d30 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
21d40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
21d50 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
21d60 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
21d70 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
21d80 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
21d90 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
21da0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
21db0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
21dc0 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
21dd0 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
21de0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
21df0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
21e00 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
21e10 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
21e20 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
21e30 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
21e40 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
21e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
21e60 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
21e70 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
21e80 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
21e90 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
21ea0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
21eb0 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
21ec0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
21ed0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
21ee0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
21ef0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
21f00 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
21f10 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
21f20 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
21f30 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
21f40 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
21f50 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
21f60 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
21f70 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
21f80 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
21f90 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
21fa0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
21fb0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
21fc0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
21fd0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
21fe0 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
21ff0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
22000 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
22010 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
22020 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
22030 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
22040 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
22050 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
22060 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
22070 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
22080 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
22090 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
220a0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
220b0 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
220c0 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
220d0 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
220e0 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
220f0 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
22100 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
22110 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
22120 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
22130 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
22140 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
22150 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
22160 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
22170 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
22180 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
22190 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
221a0 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
221b0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
221c0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
221d0 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
221e0 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
221f0 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
22200 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
22210 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
22220 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
22230 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
22240 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
22250 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
22260 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
22270 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
22280 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
22290 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
222a0 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
222b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
222c0 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
222d0 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
222e0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
222f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
22300 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
22310 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
22320 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
22330 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
22340 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
22350 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
22360 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
22370 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
22380 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
22390 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
223a0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
223b0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
223c0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
223d0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
223e0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
223f0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
22400 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
22410 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
22420 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
22430 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
22440 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
22450 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
22460 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
22470 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
22480 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
22490 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
224a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
224b0 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
224c0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
224d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
224e0 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
224f0 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
22500 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
22510 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
22520 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
22530 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
22540 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
22550 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
22560 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
22570 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
22580 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
22590 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
225a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
225b0 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
225c0 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
225d0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
225e0 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
225f0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
22600 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
22610 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
22620 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
22630 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
22640 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
22650 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
22660 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
22670 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
22680 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
22690 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
226a0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
226b0 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
226c0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
226d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
226e0 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
226f0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
22700 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
22710 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
22720 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
22730 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
22740 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
22750 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
22760 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
22770 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
22780 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
22790 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
227a0 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
227b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
227c0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
227d0 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
227e0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
227f0 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
22800 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
22810 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
22820 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
22830 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
22840 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
22850 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
22860 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
22870 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
22880 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
22890 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
228a0 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
228b0 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
228c0 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
228d0 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
228e0 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
228f0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
22900 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
22910 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
22920 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
22930 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
22940 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
22950 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
22960 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
22970 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
22980 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
22990 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
229a0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
229b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
229c0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
229d0 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
229e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
229f0 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
22a00 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
22a10 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
22a20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
22a30 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
22a40 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
22a50 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
22a60 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
22a70 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
22a80 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
22a90 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
22aa0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
22ab0 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
22ac0 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
22ad0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
22ae0 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
22af0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
22b00 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
22b10 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
22b20 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
22b30 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
22b40 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
22b50 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
22b60 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
22b70 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
22b80 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
22b90 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
22ba0 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
22bb0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
22bc0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
22bd0 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
22be0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
22bf0 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
22c00 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
22c10 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
22c20 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
22c30 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
22c40 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
22c50 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
22c60 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
22c70 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
22c80 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
22c90 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
22ca0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
22cb0 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
22cc0 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
22cd0 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
22ce0 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
22cf0 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
22d00 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
22d10 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
22d20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
22d30 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
22d40 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
22d50 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
22d60 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
22d70 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
22d80 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
22d90 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
22da0 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
22db0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
22dc0 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
22dd0 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
22de0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
22df0 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
22e00 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
22e10 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
22e20 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
22e30 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
22e40 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
22e50 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
22e60 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
22e70 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
22e80 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
22e90 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
22ea0 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
22eb0 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
22ec0 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
22ed0 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
22ee0 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
22ef0 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
22f00 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
22f10 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
22f20 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
22f30 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
22f40 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f  . .** ^(On windo
22f50 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
22f60 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
22f70 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
22f80 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
22f90 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
22fa0 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  C:").)^.**.** [[
22fb0 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
22fc0 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
22fd0 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
22fe0 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
22ff0 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
23000 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
23010 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
23020 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
23030 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
23040 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
23050 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
23060 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73  * SQLite and its
23070 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73   built-in [VFSes
23080 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a  ] interpret the.
23090 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65  ** following que
230a0 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
230b0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
230c0 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
230d0 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
230e0 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
230f0 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
23100 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
23110 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
23120 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
23130 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
23140 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
23150 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
23160 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
23170 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
23180 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
23190 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
231a0 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
231b0 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
231c0 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
231d0 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
231e0 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
231f0 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
23200 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
23210 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
23220 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
23230 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
23240 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
23250 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
23260 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
23270 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
23280 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
23290 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
232a0 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
232b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
232c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
232d0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
232e0 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
232f0 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
23300 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
23310 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a  r "ro", "rw",.**
23320 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22       "rwc", or "
23330 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74  memory". Attempt
23340 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
23350 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
23360 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72   is.**     an er
23370 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e  ror)^. .**     ^
23380 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69  If "ro" is speci
23390 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64  fied, then the d
233a0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
233b0 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  d for read-only 
233c0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
233d0 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b  just as if the [
233e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
233f0 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62  ONLY] flag had b
23400 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a  een set in the .
23410 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67  **     third arg
23420 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
23430 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20  _open_v2(). ^If 
23440 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
23450 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
23460 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
23470 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
23480 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
23490 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
234a0 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
234b0 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
234c0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
234d0 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
234e0 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
234f0 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
23500 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
23510 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
23520 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
23530 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
23540 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
23550 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
23560 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64  TE.  ^If the mod
23570 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  e option is.**  
23580 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72     set to "memor
23590 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b  y" then a pure [
235a0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
235b0 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72  se] that never r
235c0 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77  eads.**     or w
235d0 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20  rites from disk 
235e0 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20  is used. ^It is 
235f0 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
23600 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a  ify a value for.
23610 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20  **     the mode 
23620 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
23630 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69  s less restricti
23640 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65  ve than that spe
23650 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
23660 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
23670 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  d in the third p
23680 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
23690 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
236a0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63  *.**   <li> <b>c
236b0 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63  ache</b>: ^The c
236c0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d  ache parameter m
236d0 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
236e0 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a  her "shared" or.
236f0 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22  **     "private"
23700 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f  . ^Setting it to
23710 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75   "shared" is equ
23720 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
23730 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51  ng the.**     SQ
23740 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
23750 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65  CACHE bit in the
23760 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
23770 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  passed to.**    
23780 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23790 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65  (). ^Setting the
237a0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
237b0 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73   to "private" is
237c0 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c   .**     equival
237d0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
237e0 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  he SQLITE_OPEN_P
237f0 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e  RIVATECACHE bit.
23800 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69  .**     ^If sqli
23810 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
23820 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63   used and the "c
23830 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20  ache" parameter 
23840 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a  is present in.**
23850 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e       a URI filen
23860 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f  ame, its value o
23870 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68  verrides any beh
23880 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20  avior requested 
23890 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
238a0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
238b0 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
238c0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
238d0 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a  CACHE flag..**.*
238e0 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c  *  <li> <b>psow<
238f0 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70  /b>: ^The psow p
23900 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74  arameter indicat
23910 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  es whether or no
23920 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f  t the.**     [po
23930 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74  wersafe overwrit
23940 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73  e] property does
23950 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70   or does not app
23960 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ly to the.**    
23970 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f   storage media o
23980 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61  n which the data
23990 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65  base file reside
239a0 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  s..**.**  <li> <
239b0 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54  b>nolock</b>: ^T
239c0 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65  he nolock parame
239d0 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
239e0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
239f0 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66  .**     which if
23a00 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69   set disables fi
23a10 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f  le locking in ro
23a20 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d  llback journal m
23a30 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20  odes.  This.**  
23a40 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72     is useful for
23a50 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74   accessing a dat
23a60 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73  abase on a files
23a70 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20  ystem that does 
23a80 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f  not.**     suppo
23a90 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75  rt locking.  Cau
23aa0 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20  tion:  Database 
23ab0 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74  corruption might
23ac0 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a   result if two.*
23ad0 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72  *     or more pr
23ae0 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f  ocesses write to
23af0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
23b00 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f  se and any one o
23b10 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70  f those.**     p
23b20 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f  rocesses uses no
23b30 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c  lock=1..**.**  <
23b40 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65  li> <b>immutable
23b50 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74  </b>: ^The immut
23b60 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69  able parameter i
23b70 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
23b80 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74  y.**     paramet
23b90 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  er that indicate
23ba0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
23bb0 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72  ase file is stor
23bc0 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61  ed on.**     rea
23bd0 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e  d-only media.  ^
23be0 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69  When immutable i
23bf0 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73  s set, SQLite as
23c00 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
23c10 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66  *     database f
23c20 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  ile cannot be ch
23c30 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61  anged, even by a
23c40 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69   process with hi
23c50 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76  gher.**     priv
23c60 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68  ilege, and so th
23c70 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
23c80 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61  ened read-only a
23c90 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a  nd all locking.*
23ca0 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65  *     and change
23cb0 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69   detection is di
23cc0 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e  sabled.  Caution
23cd0 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d  : Setting the im
23ce0 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70  mutable.**     p
23cf0 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74  roperty on a dat
23d00 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20  abase file that 
23d10 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61  does in fact cha
23d20 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a  nge can result.*
23d30 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65  *     in incorre
23d40 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  ct query results
23d50 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
23d60 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e  CORRUPT] errors.
23d70 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f  .**     See also
23d80 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  : [SQLITE_IOCAP_
23d90 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20  IMMUTABLE]..**  
23da0 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a       .** </ul>.*
23db0 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67  *.** ^Specifying
23dc0 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61   an unknown para
23dd0 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65  meter in the que
23de0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
23df0 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a  a URI is not an.
23e00 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72  ** error.  Futur
23e10 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
23e20 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72  Lite might under
23e30 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c  stand additional
23e40 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
23e50 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65  ters.  See "[que
23e60 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69  ry parameters wi
23e70 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69  th special meani
23e80 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66  ng to SQLite]" f
23e90 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
23ea0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
23eb0 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
23ec0 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68  me examples]] <h
23ed0 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  3>URI filename e
23ee0 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  xamples</h3>.**.
23ef0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
23f00 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65  ="1" align=cente
23f10 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  r cellpadding=5>
23f20 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49  .** <tr><th> URI
23f30 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20   filenames <th> 
23f40 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c  Results.** <tr><
23f50 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
23f60 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
23f70 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65     Open the file
23f80 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
23f90 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
23fa0 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ory..** <tr><td>
23fb0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
23fc0 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20  /data.db<br>.** 
23fd0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
23fe0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23ff0 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20  db <br> .**     
24000 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61       file://loca
24010 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f  lhost/home/fred/
24020 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64  data.db <br> <td
24030 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
24040 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
24050 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
24060 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c  d/data.db"..** <
24070 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64  tr><td> file://d
24080 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65  arkstar/home/fre
24090 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  d/data.db <td> .
240a0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
240b0 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22  rror. "darkstar"
240c0 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e   is not a recogn
240d0 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a  ized authority..
240e0 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65  ** <tr><td style
240f0 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f  ="white-space:no
24100 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20  wrap"> .**      
24110 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44      file:///C:/D
24120 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32  ocuments%20and%2
24130 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44  0Settings/fred/D
24140 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a  esktop/data.db.*
24150 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f  *     <td> Windo
24160 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68  ws only: Open th
24170 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
24180 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74   on fred's deskt
24190 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20  op on drive.**  
241a0 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65          C:. Note
241b0 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73   that the %20 es
241c0 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65  caping in this e
241d0 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74  xample is not st
241e0 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20  rictly .**      
241f0 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20      necessary - 
24200 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73  space characters
24210 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74   can be used lit
24220 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20  erally.**       
24230 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61     in URI filena
24240 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  mes..** <tr><td>
24250 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
24260 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76  de=ro&cache=priv
24270 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  ate <td> .**    
24280 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
24290 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
242a0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
242b0 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ry for read-only
242c0 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20   access..**     
242d0 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20       Regardless 
242e0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
242f0 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  t shared-cache m
24300 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
24310 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  y.**          de
24320 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69  fault, use a pri
24330 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c  vate cache..** <
24340 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
24350 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f  me/fred/data.db?
24360 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65  vfs=unix-dotfile
24370 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20   <td>.**        
24380 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f    Open file "/ho
24390 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
243a0 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61  . Use the specia
243b0 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66  l VFS "unix-dotf
243c0 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20  ile".**         
243d0 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66   that uses dot-f
243e0 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66  iles in place of
243f0 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20   posix advisory 
24400 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e  locking..** <tr>
24410 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
24420 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
24430 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
24440 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
24450 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
24460 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
24470 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
24480 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
24490 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
244a0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
244b0 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
244c0 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
244d0 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
244e0 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
244f0 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
24500 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
24510 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
24520 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
24530 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
24540 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
24550 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
24560 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
24570 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
24580 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
24590 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
245a0 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
245b0 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
245c0 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
245d0 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
245e0 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
245f0 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
24600 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
24610 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
24620 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
24630 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
24640 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
24650 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
24660 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
24670 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
24680 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
24690 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
246a0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
246b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
246c0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
246d0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
246e0 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
246f0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
24700 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
24710 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
24720 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
24730 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
24740 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
24750 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
24760 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
24770 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
24780 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
24790 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
247a0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
247b0 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
247c0 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
247d0 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
247e0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
247f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
24800 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
24810 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
24820 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
24830 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
24840 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
24850 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
24860 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ng sqlite3_open(
24870 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
24880 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69  n_v2().  Otherwi
24890 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
248a0 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
248b0 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
248c0 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
248d0 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  may fail..**.** 
248e0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
248f0 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
24900 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  y].*/.SQLITE_API
24910 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
24920 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ALL sqlite3_open
24930 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
24940 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
24950 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
24960 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
24970 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
24980 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
24990 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
249a0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
249b0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
249c0 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  LL sqlite3_open1
249d0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
249e0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
249f0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
24a00 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
24a10 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
24a20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
24a30 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
24a40 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
24a50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
24a60 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65  CALL sqlite3_ope
24a70 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
24a80 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
24a90 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
24aa0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
24ab0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
24ac0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
24ad0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
24ae0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
24af0 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
24b00 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
24b10 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
24b20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
24b30 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
24b40 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
24b50 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
24b60 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
24b70 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
24b80 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
24b90 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
24ba0 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
24bb0 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
24bc0 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
24bd0 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
24be0 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
24bf0 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
24c00 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
24c10 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
24c20 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
24c30 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
24c40 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24c50 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
24c60 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
24c70 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
24c80 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
24c90 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
24ca0 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
24cb0 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
24cc0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
24cd0 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
24ce0 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
24cf0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
24d00 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
24d10 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
24d20 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
24d30 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
24d40 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
24d50 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
24d60 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
24d70 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
24d80 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
24d90 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
24da0 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
24db0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
24dc0 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
24dd0 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
24de0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24df0 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
24e00 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
24e10 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
24e20 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
24e30 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
24e40 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
24e50 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
24e60 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
24e70 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
24e80 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
24e90 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
24ea0 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
24eb0 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
24ec0 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
24ed0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
24ee0 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
24ef0 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
24f00 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
24f10 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
24f20 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24f30 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
24f40 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
24f50 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
24f60 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
24f70 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
24f80 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
24f90 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
24fa0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
24fb0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
24fc0 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
24fd0 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
24fe0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
24ff0 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
25000 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
25010 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
25020 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
25030 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
25040 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
25050 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
25060 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
25070 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
25080 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
25090 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
250a0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
250b0 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
250c0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
250d0 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
250e0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
250f0 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
25100 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
25110 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
25120 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
25130 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
25140 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
25150 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
25160 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
25170 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
25180 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
25190 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
251a0 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
251b0 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
251c0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
251d0 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
251e0 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
251f0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
25200 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
25210 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
25220 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
25230 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
25240 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
25250 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
25260 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
25270 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
25280 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
25290 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
252a0 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
252b0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
252c0 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
252d0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
252e0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
252f0 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
25300 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
25310 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
25320 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
25330 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
25340 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
25350 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
25360 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  st char *SQLITE_
25370 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
25380 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
25390 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
253a0 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
253b0 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45  *zParam);.SQLITE
253c0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
253d0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
253e0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
253f0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
25400 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
25410 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
25420 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
25430 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54  ite3_int64 SQLIT
25440 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
25450 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73  3_uri_int64(cons
25460 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63  t char*, const c
25470 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  har*, sqlite3_in
25480 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t64);.../*.** CA
25490 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
254a0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
254b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
254c0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te3.**.** ^If th
254d0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71  e most recent sq
254e0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
254f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
25500 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63   .** [database c
25510 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69  onnection] D fai
25520 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71  led, then the sq
25530 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29  lite3_errcode(D)
25540 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
25550 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
25560 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
25570 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  or [extended res
25580 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
25590 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a  at.** API call..
255a0 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  ** If the most r
255b0 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77  ecent API call w
255c0 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a  as successful,.*
255d0 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
255e0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
255f0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
25600 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
25610 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
25620 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
25630 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
25640 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
25650 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
25660 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
25670 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
25680 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
25690 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
256a0 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
256b0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
256c0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
256d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
256e0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
256f0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
25700 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
25710 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
25720 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
25730 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
25740 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
25750 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
25760 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
25770 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
25780 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
25790 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
257a0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
257b0 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
257c0 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
257d0 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
257e0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
257f0 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
25800 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
25810 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
25820 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
25830 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
25840 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
25850 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
25860 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
25870 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25880 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
25890 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
258a0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
258b0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
258c0 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
258d0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
258e0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
258f0 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
25900 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
25910 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
25920 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
25930 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
25940 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
25950 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
25960 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
25970 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
25980 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
25990 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
259a0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
259b0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
259c0 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
259d0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
259e0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
259f0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
25a00 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
25a10 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
25a20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
25a30 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
25a40 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
25a50 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
25a60 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
25a70 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
25a80 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
25a90 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
25aa0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
25ab0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
25ac0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25ad0 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
25ae0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
25af0 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
25b00 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
25b10 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
25b20 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
25b30 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
25b40 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
25b50 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
25b60 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
25b70 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
25b80 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
25b90 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
25ba0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
25bb0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
25bc0 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
25bd0 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
25be0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
25bf0 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
25c00 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
25c10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
25c20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
25c30 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
25c40 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
25c50 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
25c60 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
25c70 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
25c80 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72  CALL sqlite3_err
25c90 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
25ca0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
25cb0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
25cc0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
25cd0 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
25ce0 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41  3 *db);.SQLITE_A
25cf0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
25d00 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
25d10 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
25d20 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
25d30 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
25d40 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
25d50 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
25d60 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45  qlite3*);.SQLITE
25d70 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
25d80 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
25d90 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69  sqlite3_errstr(i
25da0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
25db0 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53  3REF: Prepared S
25dc0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
25dd0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
25de0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25df0 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
25e00 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
25e10 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
25e20 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
25e30 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
25e40 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a   statement that.
25e50 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70  ** has been comp
25e60 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79  iled into binary
25e70 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61   form and is rea
25e80 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  dy to be evaluat
25e90 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20  ed..**.** Think 
25ea0 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  of each SQL stat
25eb0 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72  ement as a separ
25ec0 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f  ate computer pro
25ed0 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72  gram.  The.** or
25ee0 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20  iginal SQL text 
25ef0 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20  is source code. 
25f00 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74   A prepared stat
25f10 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a  ement object .**
25f20 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64   is the compiled
25f30 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41   object code.  A
25f40 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63  ll SQL must be c
25f50 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a  onverted into a.
25f60 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
25f70 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20  ement before it 
25f80 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a  can be run..**.*
25f90 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65  * The life-cycle
25fa0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73   of a prepared s
25fb0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
25fc0 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b  usually goes lik
25fd0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
25fe0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
25ff0 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  e the prepared s
26000 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
26010 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
26020 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a  repare_v2()]..**
26030 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
26040 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73  s to [parameters
26050 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
26060 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
26070 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
26080 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
26090 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
260a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
260b0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
260c0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
260d0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
260e0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
260f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
26100 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
26110 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
26120 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
26130 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
26140 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
26150 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
26160 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
26170 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  ()]..** </ol>.*/
26180 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
26190 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
261a0 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
261b0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
261c0 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d  time Limits.** M
261d0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
261e0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
261f0 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
26200 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
26210 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
26220 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
26230 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
26240 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
26250 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
26260 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
26270 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
26280 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
26290 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
262a0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
262b0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
262c0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
262d0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
262e0 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
262f0 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
26300 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
26310 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
26320 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
26330 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
26340 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
26350 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
26360 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
26370 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
26380 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
26390 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
263a0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
263b0 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
263c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
263d0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
263e0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
263f0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
26400 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
26410 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
26420 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
26430 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
26440 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
26450 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
26460 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
26470 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
26480 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
26490 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
264a0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
264b0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
264c0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
264d0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
264e0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
264f0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
26500 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
26510 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
26520 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
26530 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
26540 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
26550 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
26560 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26570 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
26580 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
26590 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
265a0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
265b0 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
265c0 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
265d0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
265e0 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
265f0 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
26600 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
26610 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
26620 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
26630 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
26640 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
26650 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
26660 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
26670 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
26680 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
26690 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
266a0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
266b0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
266c0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
266d0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
266e0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
266f0 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
26700 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
26710 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
26720 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
26730 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
26740 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
26750 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
26760 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
26770 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
26780 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
26790 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
267a0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
267b0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
267c0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
267d0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
267e0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
267f0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
26800 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
26810 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
26820 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
26830 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
26840 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
26850 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
26860 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
26870 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
26880 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
26890 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
268a0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
268b0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
268c0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
268d0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
268e0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
268f0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
26900 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
26910 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
26920 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
26930 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
26940 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
26950 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
26960 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
26970 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49  eleases..*/.SQLI
26980 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
26990 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
269a0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
269b0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
269c0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
269d0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
269e0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
269f0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
26a00 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
26a10 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
26a20 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
26a30 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
26a40 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
26a50 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
26a60 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
26a70 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
26a80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
26a90 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
26aa0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
26ab0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
26ac0 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
26ad0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
26ae0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
26af0 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
26b00 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
26b10 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
26b20 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
26b30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26b40 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
26b50 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
26b60 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
26b70 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
26b80 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
26b90 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
26ba0 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
26bb0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26bc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
26bd0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
26be0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
26bf0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
26c00 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
26c10 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
26c20 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
26c30 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
26c40 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26c50 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
26c60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
26c70 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
26c80 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
26c90 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
26ca0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
26cb0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
26cc0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
26cd0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
26ce0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
26cf0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
26d00 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
26d10 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
26d20 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
26d30 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26d40 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
26d50 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
26d60 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
26d70 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
26d80 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
26d90 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
26da0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
26db0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
26dc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26dd0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
26de0 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
26df0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
26e00 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
26e10 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26e20 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
26e30 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
26e40 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
26e50 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
26e60 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
26e70 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
26e80 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
26e90 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
26ea0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
26eb0 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
26ec0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
26ed0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
26ee0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
26ef0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
26f00 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
26f10 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
26f20 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
26f30 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
26f40 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
26f50 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
26f60 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
26f70 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
26f80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
26f90 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
26fa0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
26fb0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
26fc0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26fd0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
26fe0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
26ff0 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
27000 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
27010 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
27020 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
27030 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
27040 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
27050 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
27060 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
27070 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
27080 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27090 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
270a0 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
270b0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
270c0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
270d0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
270e0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
270f0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
27100 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
27110 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
27120 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
27130 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
27140 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
27150 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
27160 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
27170 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
27180 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
27190 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
271a0 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
271b0 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
271c0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
271d0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
271e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
271f0 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
27200 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
27210 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
27220 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
27230 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
27240 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
27250 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ers.</dd>)^.**.*
27260 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
27270 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d  _WORKER_THREADS]
27280 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27290 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
272a0 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ADS</dt>.** <dd>
272b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
272c0 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20  er of auxiliary 
272d0 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74  worker threads t
272e0 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20  hat a single.** 
272f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27300 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c  ent] may start.<
27310 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
27320 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
27330 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
27340 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27350 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
27360 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
27370 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
27380 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
27390 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
273a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
273b0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
273c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
273d0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
273e0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
273f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
27400 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
27410 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
27420 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
27430 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
27440 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
27450 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
27460 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
27470 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
27480 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
27490 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
274a0 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
274b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
274c0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
274d0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
274e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
274f0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
27500 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
27510 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27520 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
27530 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
27540 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27550 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
27560 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a  S           11..
27570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27580 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
27590 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
275a0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
275b0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
275c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
275d0 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  te3.** CONSTRUCT
275e0 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
275f0 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
27600 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
27610 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
27620 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
27630 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
27640 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
27650 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
27660 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
27670 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
27680 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
27690 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
276a0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
276b0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
276c0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
276d0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
276e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
276f0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
27700 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
27710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27720 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
27730 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
27740 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
27750 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
27760 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
27770 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
27780 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
27790 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
277a0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
277b0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
277c0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
277d0 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
277e0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
277f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
27800 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
27810 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
27820 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
27830 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
27840 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
27850 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
27860 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
27870 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
27880 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
27890 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
278a0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69  positive, then i
278b0 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  t is the.** numb
278c0 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64  er of bytes read
278d0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66   from zSql.  ^If
278e0 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20   nByte is zero, 
278f0 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64  then no prepared
27900 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73  .** statement is
27910 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49   generated..** I
27920 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
27930 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ws that the supp
27940 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
27950 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
27960 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20  hen.** there is 
27970 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61  a small performa
27980 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
27990 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
279a0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
279b0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
279c0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
279d0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
279e0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
279f0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
27a00 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nator..**.** ^If
27a10 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
27a20 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
27a30 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
27a40 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
27a50 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
27a60 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
27a70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
27a80 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
27a90 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
27aa0 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
27ab0 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
27ac0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
27ad0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
27ae0 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
27af0 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
27b00 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
27b10 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
27b20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
27b30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27b40 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
27b50 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
27b60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27b70 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
27b80 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
27b90 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
27ba0 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
27bb0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
27bc0 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
27bd0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
27be0 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
27bf0 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
27c00 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
27c10 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
27c20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
27c30 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
27c40 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
27c50 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
27c60 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
27c70 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
27c80 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
27c90 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
27ca0 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
27cb0 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
27cc0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
27cd0 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
27ce0 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
27cf0 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
27d00 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
27d10 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
27d20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
27d30 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
27d40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
27d50 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
27d60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
27d70 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
27d80 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
27d90 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
27da0 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
27db0 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
27dc0 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
27dd0 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
27de0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
27df0 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
27e00 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
27e10 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
27e20 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
27e30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
27e40 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
27e50 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
27e60 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
27e70 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
27e80 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
27e90 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
27ea0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
27eb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
27ec0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
27ed0 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
27ee0 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
27ef0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
27f00 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
27f10 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
27f20 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
27f30 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
27f40 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
27f50 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
27f60 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
27f70 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
27f80 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
27f90 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
27fa0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
27fb0 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
27fc0 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
27fd0 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
27fe0 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
27ff0 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
28000 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
28010 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
28020 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
28030 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
28040 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
28050 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
28060 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
28070 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
28080 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
28090 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
280a0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
280b0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
280c0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
280d0 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
280e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
280f0 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
28100 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
28110 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
28120 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
28130 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
28140 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
28150 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
28160 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
28170 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
28180 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
28190 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
281a0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
281b0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
281c0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
281d0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
281e0 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
281f0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
28200 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
28210 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
28220 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
28230 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
28240 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
28250 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
28260 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
28270 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
28280 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
28290 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
282a0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
282b0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
282c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
282d0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
282e0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
282f0 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
28300 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
28310 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
28320 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
28330 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
28340 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
28350 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
28360 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
28370 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
28380 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
28390 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
283a0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
283b0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
283c0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
283d0 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
283e0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
283f0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
28400 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
28410 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
28420 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
28430 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
28440 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
28450 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
28460 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
28470 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
28480 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
28490 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
284a0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
284b0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
284c0 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  >.*/.SQLITE_API 
284d0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
284e0 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  LL sqlite3_prepa
284f0 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
28500 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
28510 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
28520 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
28530 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
28540 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
28550 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
28560 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
28570 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
28580 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
28590 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
285a0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
285b0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
285c0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
285d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
285e0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
285f0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
28600 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
28610 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
28620 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
28630 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
28640 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28650 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
28660 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
28670 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
28680 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
28690 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
286a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
286b0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
286c0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
286d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
286e0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
286f0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
28700 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
28710 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
28720 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
28730 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
28740 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
28750 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
28760 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
28770 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
28780 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
28790 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
287a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
287b0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
287c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
287d0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
287e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
287f0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
28800 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
28810 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
28820 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
28830 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
28840 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
28850 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
28860 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
28870 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
28880 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
28890 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
288a0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
288b0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
288c0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
288d0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
288e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
288f0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
28900 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28910 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
28920 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
28930 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
28940 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
28950 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
28960 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
28970 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
28980 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
28990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
289a0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
289b0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
289c0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
289d0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
289e0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
289f0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
28a00 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
28a10 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
28a20 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
28a30 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
28a40 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
28a50 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
28a60 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
28a70 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
28a80 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
28a90 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
28aa0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
28ab0 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
28ac0 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
28ad0 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
28ae0 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
28af0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28b00 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
28b10 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
28b20 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
28b30 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
28b40 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
28b50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
28b60 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  v2()]..*/.SQLITE
28b70 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
28b80 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
28b90 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
28ba0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
28bb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28bc0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
28bd0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
28be0 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
28bf0 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  base.** METHOD: 
28c00 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
28c10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28c20 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
28c30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
28c40 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
28c50 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
28c60 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
28c70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
28c80 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
28c90 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
28ca0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
28cb0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
28cc0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
28cd0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
28ce0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
28cf0 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
28d00 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
28d10 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
28d20 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
28d30 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
28d40 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
28d50 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
28d60 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
28d70 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
28d80 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
28d90 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
28da0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
28db0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
28dc0 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
28dd0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
28de0 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
28df0 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
28e00 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
28e10 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
28e20 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
28e30 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
28e40 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
28e50 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
28e60 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
28e70 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
28e80 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
28e90 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
28ea0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
28eb0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
28ec0 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
28ed0 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
28ee0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
28ef0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
28f00 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
28f10 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
28f20 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
28f30 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
28f40 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
28f50 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
28f60 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
28f70 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
28f80 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
28f90 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
28fa0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
28fb0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
28fc0 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
28fd0 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
28fe0 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
28ff0 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
29000 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
29010 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
29020 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
29030 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
29040 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
29050 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
29060 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
29070 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
29080 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
29090 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
290a0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
290b0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
290c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
290d0 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
290e0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
290f0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
29100 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
29110 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  n disk..*/.SQLIT
29120 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
29130 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
29140 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73  _stmt_readonly(s
29150 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
29160 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
29170 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
29180 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  If A Prepared St
29190 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e  atement Has Been
291a0 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44   Reset.** METHOD
291b0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
291c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
291d0 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
291e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
291f0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
29200 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
29210 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29220 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
29230 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
29240 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
29250 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
29260 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20   has not run to 
29270 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f  completion and/o
29280 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65  r has not .** be
29290 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b  en reset using [
292a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
292b0 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
292c0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a  _stmt_busy(S).**
292d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
292e0 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73  ns false if S is
292f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
29300 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20    If S is not a 
29310 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
29320 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f   and is not a po
29330 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64  inter to a valid
29340 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29350 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c  ment].** object,
29360 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
29370 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  or is undefined 
29380 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
29390 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
293a0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
293b0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f  an be used in co
293c0 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74  mbination [sqlit
293d0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a  e3_next_stmt()].
293e0 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ** to locate all
293f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29400 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
29410 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
29420 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
29430 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20  hat are in need 
29440 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20  of being reset. 
29450 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65   This can be use
29460 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c  d,.** for exampl
29470 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63  e, in diagnostic
29480 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61   routines to sea
29490 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64  rch for prepared
294a0 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20   .** statements 
294b0 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67  that are holding
294c0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f   a transaction o
294d0 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
294e0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
294f0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74  DCALL sqlite3_st
29500 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f  mt_busy(sqlite3_
29510 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
29520 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
29530 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
29540 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
29550 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
29560 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
29570 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
29580 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
29590 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
295a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
295b0 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
295c0 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
295d0 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
295e0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
295f0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
29600 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
29610 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
29620 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
29630 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
29640 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
29650 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
29660 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
29670 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
29680 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
29690 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
296a0 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
296b0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
296c0 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
296d0 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
296e0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
296f0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
29700 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
29710 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
29720 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
29730 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
29740 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
29750 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
29760 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29770 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
29780 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
29790 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
297a0 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
297b0 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
297c0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
297d0 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
297e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54  qlite3_value.  T
297f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
29800 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65  alue_dup()] inte
29810 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
29820 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61  d to construct a
29830 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74   new .** protect
29840 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29850 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65   from an unprote
29860 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29870 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
29880 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
29890 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
298a0 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
298b0 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
298c0 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
298d0 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  n internal mutex
298e0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
298f0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
29900 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29910 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
29920 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
29930 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
29940 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29950 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
29960 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
29970 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
29980 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
29990 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
299a0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
299b0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
299c0 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
299d0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
299e0 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
299f0 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
29a00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
29a10 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
29a20 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
29a30 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
29a40 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
29a50 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
29a60 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
29a70 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
29a80 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
29a90 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
29aa0 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
29ab0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
29ac0 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
29ad0 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
29ae0 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
29af0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
29b00 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
29b10 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
29b20 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
29b30 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
29b40 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
29b50 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
29b60 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
29b70 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
29b80 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
29b90 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
29ba0 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
29bb0 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
29bc0 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
29bd0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
29be0 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
29bf0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
29c00 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
29c10 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
29c20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
29c30 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
29c40 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
29c50 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
29c60 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
29c70 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
29c80 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
29c90 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
29ca0 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
29cb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
29cc0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
29cd0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
29ce0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
29cf0 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
29d00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
29d10 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
29d20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
29d30 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
29d40 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29d50 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
29d60 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
29d70 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
29d80 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
29d90 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
29da0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
29db0 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
29dc0 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
29dd0 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
29de0 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
29df0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
29e00 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65  ject.  ^A pointe
29e10 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
29e20 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
29e30 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
29e40 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
29e50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29e60 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
29e70 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
29e80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
29e90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
29ea0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
29eb0 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
29ec0 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
29ed0 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
29ee0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
29ef0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
29f00 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
29f10 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
29f20 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
29f30 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
29f40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
29f50 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
29f60 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
29f70 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
29f80 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
29f90 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
29fa0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
29fb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
29fc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
29fd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
29fe0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
29ff0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2a000 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ents.** KEYWORDS
2a010 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  : {host paramete
2a020 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  r} {host paramet
2a030 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ers} {host param
2a040 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45  eter name}.** KE
2a050 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72  YWORDS: {SQL par
2a060 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72  ameter} {SQL par
2a070 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65  ameters} {parame
2a080 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20  ter binding}.** 
2a090 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2a0a0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  stmt.**.** ^(In 
2a0b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2a0c0 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20  t text input to 
2a0d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a0e0 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
2a0f0 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
2a100 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
2a110 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d  aced by a [param
2a120 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68  eter] that match
2a130 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77  es one of follow
2a140 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73  ing.** templates
2a150 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2a160 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
2a170 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
2a180 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
2a190 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
2a1a0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2a1b0 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20  n the templates 
2a1c0 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65  above, NNN repre
2a1d0 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72  sents an integer
2a1e0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
2a1f0 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20   VVV represents 
2a200 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  an alphanumeric 
2a210 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e  identifier.)^  ^
2a220 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
2a230 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
2a240 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
2a250 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
2a260 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
2a270 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
2a280 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
2a290 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2a2a0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
2a2b0 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
2a2c0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2a2d0 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
2a2e0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2a2f0 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a  tines is always.
2a300 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
2a310 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2a320 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
2a330 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
2a340 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a350 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
2a360 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  s..**.** ^The se
2a370 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2a380 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2a390 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
2a3a0 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54  to be set..** ^T
2a3b0 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
2a3c0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
2a3d0 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57   index of 1.  ^W
2a3e0 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  hen the same nam
2a3f0 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ed.** SQL parame
2a400 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65  ter is used more
2a410 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f   than once, seco
2a420 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
2a430 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73  t.** occurrences
2a440 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69   have the same i
2a450 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73  ndex as the firs
2a460 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a  t occurrence..**
2a470 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20   ^The index for 
2a480 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
2a490 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
2a4a0 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
2a4b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a4c0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
2a4d0 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
2a4e0 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66   ^The index.** f
2a4f0 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65  or "?NNN" parame
2a500 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75  ters is the valu
2a510 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68  e of NNN..** ^Th
2a520 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
2a530 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
2a540 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
2a550 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
2a560 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
2a570 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
2a580 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
2a590 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
2a5a0 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
2a5b0 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
2a5c0 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
2a5d0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
2a5e0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
2a5f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2a600 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
2a610 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a620 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  t16().** or sqli
2a630 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
2a640 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2a650 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  r then the fourt
2a660 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  h parameter.** i
2a670 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68  s ignored and th
2a680 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20  e end result is 
2a690 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69  the same as sqli
2a6a0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e  te3_bind_null().
2a6b0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
2a6c0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
2a6d0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
2a6e0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
2a6f0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
2a700 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2a710 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
2a720 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
2a730 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
2a740 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
2a750 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
2a760 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
2a770 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2a780 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
2a790 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2a7a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2a7b0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2a7c0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2a7d0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
2a7e0 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68   then the length
2a7f0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
2a800 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2a810 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
2a820 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
2a830 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20  rminator..** If 
2a840 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2a850 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2a860 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e  bind_blob() is n
2a870 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a  egative, then.**
2a880 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2a890 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
2a8a0 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  f a non-negative
2a8b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2a8c0 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  r is provided to
2a8d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a8e0 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  xt().** or sqlit
2a8f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2a900 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2a910 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a  _text64() then.*
2a920 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  * that parameter
2a930 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
2a940 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72  e offset.** wher
2a950 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
2a960 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72  ator would occur
2a970 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74   assuming the st
2a980 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a  ring were NUL.**
2a990 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
2a9a0 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
2a9b0 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74  ers occur at byt
2a9c0 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74  e offsets less t
2a9d0 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75  han .** the valu
2a9e0 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  e of the fourth 
2a9f0 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74  parameter then t
2aa00 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
2aa10 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a  ing value will.*
2aa20 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  * contain embedd
2aa30 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65  ed NULs.  The re
2aa40 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
2aa50 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74  ons involving st
2aa60 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d  rings.** with em
2aa70 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
2aa80 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2aa90 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
2aaa0 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20  ent to the BLOB 
2aab0 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69  and string bindi
2aac0 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  ng interfaces.**
2aad0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
2aae0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
2aaf0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
2ab00 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
2ab10 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
2ab20 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54  hed with it.  ^T
2ab30 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
2ab40 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69   called.** to di
2ab50 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
2ab60 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e  B or string even
2ab70 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
2ab80 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a  bind API fails..
2ab90 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
2aba0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
2abb0 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
2abc0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
2abd0 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
2abe0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
2abf0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
2ac00 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
2ac10 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
2ac20 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2ac30 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
2ac40 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
2ac50 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
2ac60 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
2ac70 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
2ac80 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
2ac90 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
2aca0 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
2acb0 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
2acc0 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
2acd0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2ace0 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
2acf0 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75   ^The sixth argu
2ad00 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2ad10 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75  bind_text64() mu
2ad20 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  st be one of.** 
2ad30 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
2ad40 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b  SQLITE_UTF16], [
2ad50 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
2ad60 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
2ad70 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69  6LE].** to speci
2ad80 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  fy the encoding 
2ad90 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74  of the text in t
2ada0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2adb0 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73  er.  If.** the s
2adc0 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
2add0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2ade0 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e  xt64() is not on
2adf0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f  e of the.** allo
2ae00 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e  wed values shown
2ae10 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68   above, or if th
2ae20 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
2ae30 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20  is different.** 
2ae40 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e  from the encodin
2ae50 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  g specified by t
2ae60 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  he sixth paramet
2ae70 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  er, then the beh
2ae80 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65  avior.** is unde
2ae90 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2aea0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
2aeb0 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
2aec0 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
2aed0 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
2aee0 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
2aef0 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65  h zeroes.  ^A ze
2af00 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
2af10 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
2af20 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
2af30 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
2af40 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
2af50 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
2af60 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
2af70 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
2af80 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
2af90 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
2afa0 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
2afb0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
2afc0 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
2afd0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
2afe0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
2aff0 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
2b000 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  nes..** ^A negat
2b010 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
2b020 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
2b030 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
2b040 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
2b050 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73  ^If any of the s
2b060 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2b070 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2b080 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
2b090 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74  pointer.** for t
2b0a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2b0b0 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20  tement] or with 
2b0c0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2b0d0 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a  ment for which.*
2b0e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2b0f0 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
2b100 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79  ed more recently
2b110 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72   than [sqlite3_r
2b120 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  eset()],.** then
2b130 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72   the call will r
2b140 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  eturn [SQLITE_MI
2b150 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73  SUSE].  If any s
2b160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a  qlite3_bind_().*
2b170 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73  * routine is pas
2b180 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20  sed a [prepared 
2b190 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2b1a0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2b1b0 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ed, the.** resul
2b1c0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  t is undefined a
2b1d0 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d  nd probably harm
2b1e0 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64  ful..**.** ^Bind
2b1f0 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
2b200 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
2b210 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
2b220 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75  utine..** ^Unbou
2b230 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
2b240 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
2b250 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
2b260 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2b270 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2b280 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
2b290 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a  success or an.**
2b2a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
2b2b0 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
2b2c0 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  rong..** ^[SQLIT
2b2d0 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20  E_TOOBIG] might 
2b2e0 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  be returned if t
2b2f0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72  he size of a str
2b300 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65  ing or BLOB.** e
2b310 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d  xceeds limits im
2b320 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  posed by [sqlite
2b330 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
2b340 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20  _LIMIT_LENGTH]) 
2b350 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  or.** [SQLITE_MA
2b360 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b  X_LENGTH]..** ^[
2b370 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
2b380 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
2b390 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
2b3a0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
2b3b0 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e  nge.  ^[SQLITE_N
2b3c0 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
2b3d0 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61  d if malloc() fa
2b3e0 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ils..**.** See a
2b3f0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2b400 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2b410 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
2b420 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b430 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
2b440 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2b450 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2b460 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2b470 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2b480 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  L sqlite3_bind_b
2b490 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2b4a0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2b4b0 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
2b4c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
2b4d0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2b4e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2b4f0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73  e3_bind_blob64(s
2b500 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b510 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2b520 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
2b530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b540 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
2b550 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
2b560 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2b570 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2b580 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
2b590 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
2b5a0 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41  ouble);.SQLITE_A
2b5b0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2b5c0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2b5d0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
2b5e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
2b5f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2b600 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2b610 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
2b620 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2b630 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
2b640 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
2b650 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2b660 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2b670 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
2b680 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  mt*, int);.SQLIT
2b690 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2b6a0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2b6b0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
2b6c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e  e3_stmt*,int,con
2b6d0 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69  st char*,int,voi
2b6e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
2b6f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2b700 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2b710 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2b720 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b730 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2b740 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
2b750 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
2b760 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2b770 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2b780 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33  d_text64(sqlite3
2b790 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2b7a0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
2b7b0 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2b7c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b7d0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2b7e0 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
2b7f0 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49   encoding);.SQLI
2b800 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2b810 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2b820 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
2b830 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2b840 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
2b850 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2b860 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2b870 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2b880 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
2b890 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2b8a0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
2b8b0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2b8c0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
2b8d0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
2b8e0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2b8f0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
2b900 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
2b910 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
2b920 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
2b930 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
2b940 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2b950 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
2b960 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
2b970 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
2b980 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
2b990 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
2b9a0 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
2b9b0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2b9c0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
2b9d0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2b9e0 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
2b9f0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
2ba00 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
2ba10 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
2ba20 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
2ba30 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
2ba40 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
2ba50 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
2ba60 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
2ba70 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
2ba80 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
2ba90 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
2baa0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2bab0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
2bac0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
2bad0 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
2bae0 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
2baf0 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
2bb00 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
2bb10 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
2bb20 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2bb30 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2bb40 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2bb50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2bb60 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
2bb70 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2bb80 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2bb90 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
2bba0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2bbb0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2bbc0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2bbd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2bbe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bbf0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
2bc00 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45   Parameter.** ME
2bc10 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2bc20 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2bc30 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2bc40 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
2bc50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2bc60 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
2bc70 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
2bc80 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2bc90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2bca0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
2bcb0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2bcc0 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
2bcd0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
2bce0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
2bcf0 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
2bd00 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
2bd10 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
2bd20 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
2bd30 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
2bd40 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
2bd50 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
2bd60 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
2bd70 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
2bd80 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
2bd90 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
2bda0 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
2bdb0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2bdc0 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
2bdd0 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
2bde0 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
2bdf0 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
2be00 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
2be10 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
2be20 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
2be30 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
2be40 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
2be50 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
2be60 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
2be70 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
2be80 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
2be90 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
2bea0 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
2beb0 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
2bec0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
2bed0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2bee0 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
2bef0 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
2bf00 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
2bf10 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
2bf20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
2bf30 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
2bf40 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
2bf50 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
2bf60 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2bf70 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
2bf80 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2bf90 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2bfa0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2bfb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2bfc0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2bfd0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2bfe0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2bff0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2c000 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2c010 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2c020 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2c030 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2c040 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2c050 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
2c060 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
2c070 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
2c080 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
2c090 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2c0a0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
2c0b0 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
2c0c0 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
2c0d0 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
2c0e0 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
2c0f0 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
2c100 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
2c110 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
2c120 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
2c130 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
2c140 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2c150 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
2c160 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2c170 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
2c180 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
2c190 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
2c1a0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
2c1b0 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
2c1c0 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
2c1d0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
2c1e0 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
2c1f0 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
2c200 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2c210 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2c220 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2c230 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2c240 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2c250 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2c260 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2c270 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2c280 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2c290 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2c2a0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2c2b0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2c2c0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2c2d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2c2e0 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
2c2f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2c300 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
2c310 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
2c320 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
2c330 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2c340 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2c350 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2c360 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
2c370 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
2c380 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
2c390 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
2c3a0 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
2c3b0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2c3c0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
2c3d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c3e0 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
2c3f0 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
2c400 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
2c410 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
2c420 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2c430 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2c440 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
2c450 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2c460 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2c470 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2c480 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
2c490 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
2c4a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2c4b0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
2c4c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2c4d0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2c4e0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
2c4f0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
2c500 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c510 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
2c520 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
2c530 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
2c540 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
2c550 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
2c560 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
2c570 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
2c580 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2c590 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2c5a0 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
2c5b0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2c5c0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2c5d0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
2c5e0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2c5f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c600 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
2c610 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
2c620 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2c630 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2c640 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
2c650 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
2c660 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
2c670 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
2c680 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
2c690 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
2c6a0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
2c6b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2c6c0 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
2c6d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2c6e0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
2c6f0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
2c700 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
2c710 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2c720 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
2c730 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2c740 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
2c750 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
2c760 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
2c770 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
2c780 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c790 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
2c7a0 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
2c7b0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
2c7c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2c7d0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
2c7e0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
2c7f0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2c800 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
2c810 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
2c820 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
2c830 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
2c840 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
2c850 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c860 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
2c870 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
2c880 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
2c890 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
2c8a0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
2c8b0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
2c8c0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
2c8d0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2c8e0 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
2c8f0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
2c900 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
2c910 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
2c920 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2c930 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2c940 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
2c950 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
2c960 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
2c970 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
2c980 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
2c990 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
2c9a0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
2c9b0 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
2c9c0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
2c9d0 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
2c9e0 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
2c9f0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2ca00 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2ca10 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
2ca20 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
2ca30 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
2ca40 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
2ca50 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
2ca60 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
2ca70 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
2ca80 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
2ca90 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
2caa0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
2cab0 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
2cac0 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
2cad0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
2cae0 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
2caf0 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c  the next..*/.SQL
2cb00 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2cb10 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
2cb20 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
2cb30 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2cb40 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51  tmt*, int N);.SQ
2cb50 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2cb60 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
2cb70 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2cb80 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
2cb90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2cba0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2cbb0 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
2cbc0 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
2cbd0 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  lt.** METHOD: sq
2cbe0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2cbf0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2cc00 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
2cc10 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
2cc20 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
2cc30 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
2cc40 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
2cc50 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
2cc60 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
2cc70 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
2cc80 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2cc90 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
2cca0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
2ccb0 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
2ccc0 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
2ccd0 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
2cce0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
2ccf0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
2cd00 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
2cd10 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
2cd20 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
2cd30 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
2cd40 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2cd50 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
2cd60 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
2cd70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2cd80 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
2cd90 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2cda0 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
2cdb0 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
2cdc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cdd0 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
2cde0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2cdf0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2ce00 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2ce10 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2ce20 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2ce30 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2ce40 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2ce50 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2ce60 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2ce70 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
2ce80 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2ce90 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
2cea0 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
2ceb0 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
2cec0 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
2ced0 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
2cee0 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
2cef0 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
2cf00 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
2cf10 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
2cf20 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2cf30 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
2cf40 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
2cf50 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2cf60 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
2cf70 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2cf80 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2cf90 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
2cfa0 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
2cfb0 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
2cfc0 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
2cfd0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
2cfe0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
2cff0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
2d000 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
2d010 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
2d020 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
2d030 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2d040 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
2d050 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2d060 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
2d070 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
2d080 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
2d090 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
2d0a0 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
2d0b0 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
2d0c0 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
2d0d0 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
2d0e0 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
2d0f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2d100 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
2d110 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
2d120 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
2d130 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
2d140 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
2d150 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
2d160 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
2d170 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
2d180 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
2d190 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
2d1a0 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
2d1b0 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
2d1c0 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
2d1d0 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
2d1e0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2d1f0 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
2d200 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
2d210 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
2d220 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
2d230 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
2d240 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
2d250 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
2d260 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
2d270 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
2d280 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
2d290 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
2d2a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2d2b0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2d2c0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
2d2d0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2d2e0 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
2d2f0 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
2d300 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
2d310 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
2d320 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2d330 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
2d340 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
2d350 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2d360 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2d370 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
2d380 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2d390 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
2d3a0 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
2d3b0 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
2d3c0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
2d3d0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
2d3e0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
2d3f0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2d400 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2d410 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2d420 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2d430 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
2d440 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d450 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2d460 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2d470 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2d480 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2d490 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
2d4a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2d4b0 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
2d4c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2d4d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2d4e0 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
2d4f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d500 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
2d510 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2d520 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2d530 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
2d540 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2d550 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2d560 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2d570 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2d580 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2d590 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
2d5a0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
2d5b0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
2d5c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2d5d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2d5e0 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
2d5f0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2d600 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2d610 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2d620 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2d630 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
2d640 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
2d650 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2d660 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2d670 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  _stmt.**.** ^(Th
2d680 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2d690 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
2d6a0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2d6b0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
2d6c0 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
2d6d0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
2d6e0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2d6f0 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
2d700 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
2d710 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
2d720 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
2d730 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
2d740 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
2d750 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
2d760 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
2d770 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
2d780 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
2d790 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2d7a0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2d7b0 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
2d7c0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2d7d0 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
2d7e0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2d7f0 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
2d800 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2d810 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
2d820 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
2d830 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
2d840 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
2d850 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
2d860 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
2d870 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
2d880 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
2d890 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
2d8a0 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
2d8b0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
2d8c0 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
2d8d0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
2d8e0 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
2d8f0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
2d900 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
2d910 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
2d920 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
2d930 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
2d940 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
2d950 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
2d960 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
2d970 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
2d980 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
2d990 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
2d9a0 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
2d9b0 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
2d9c0 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
2d9d0 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
2d9e0 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
2d9f0 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
2da00 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
2da10 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2da20 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
2da30 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
2da40 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
2da50 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
2da60 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
2da70 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
2da80 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
2da90 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
2daa0 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
2dab0 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
2dac0 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
2dad0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2dae0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2daf0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2db00 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
2db10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2db20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2db30 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  nst void *SQLITE
2db40 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2db50 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2db60 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2db70 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2db80 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
2db90 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2dba0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2dbb0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2dbc0 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
2dbd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
2dbe0 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
2dbf0 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
2dc00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2dc10 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
2dc20 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2dc30 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
2dc40 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2dc50 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
2dc60 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
2dc70 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2dc80 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
2dc90 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
2dca0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
2dcb0 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
2dcc0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
2dcd0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
2dce0 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
2dcf0 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
2dd00 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
2dd10 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
2dd20 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
2dd30 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
2dd40 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
2dd50 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
2dd60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2dd70 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
2dd80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2dd90 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
2dda0 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
2ddb0 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
2ddc0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
2ddd0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2dde0 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
2ddf0 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
2de00 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
2de10 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
2de20 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
2de30 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
2de40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
2de50 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
2de60 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
2de70 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
2de80 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
2de90 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
2dea0 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
2deb0 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
2dec0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
2ded0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
2dee0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
2def0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
2df00 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
2df10 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
2df20 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
2df30 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
2df40 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
2df50 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
2df60 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
2df70 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
2df80 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
2df90 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
2dfa0 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
2dfb0 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
2dfc0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2dfd0 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
2dfe0 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
2dff0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2e000 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
2e010 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
2e020 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
2e030 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
2e040 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
2e050 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
2e060 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
2e070 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
2e080 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
2e090 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a  urs within an.**
2e0a0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2e0b0 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
2e0c0 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
2e0d0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
2e0e0 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
2e0f0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ing..**.** ^[SQL
2e100 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
2e110 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
2e120 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
2e130 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
2e140 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
2e150 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2e160 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2e170 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
2e180 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
2e190 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
2e1a0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2e1b0 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
2e1c0 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
2e1d0 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
2e1e0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
2e1f0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te..**.** ^If th
2e200 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2e210 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
2e220 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
2e230 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
2e240 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
2e250 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
2e260 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
2e270 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
2e280 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
2e290 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
2e2a0 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
2e2b0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
2e2c0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2e2d0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
2e2e0 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
2e2f0 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
2e300 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
2e310 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
2e320 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  * ^[SQLITE_ERROR
2e330 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
2e340 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
2e350 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
2e360 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
2e370 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
2e380 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2e390 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2e3a0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
2e3b0 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
2e3c0 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
2e3d0 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
2e3e0 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
2e3f0 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  g()]..** ^With t
2e400 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2e410 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
2e420 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2e430 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
2e440 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
2e450 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
2e460 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
2e470 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
2e480 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
2e490 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
2e4a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2e4b0 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
2e4c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e4d0 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22  ent].  ^In the "
2e4e0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
2e4f0 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
2e500 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
2e510 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
2e520 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
2e530 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
2e540 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
2e550 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
2e560 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
2e570 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
2e580 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
2e590 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
2e5a0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2e5b0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
2e5c0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
2e5d0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2e5e0 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
2e5f0 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
2e600 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
2e610 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2e620 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
2e630 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
2e640 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
2e650 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
2e660 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
2e670 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
2e680 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
2e690 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
2e6a0 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
2e6b0 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
2e6c0 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69  ** For all versi
2e6d0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70  ons of SQLite up
2e6e0 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e   to and includin
2e6f0 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61  g 3.6.23.1, a ca
2e700 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2e710 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72  3_reset()] was r
2e720 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71  equired after sq
2e730 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74  lite3_step() ret
2e740 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a  urned anything.*
2e750 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  * other than [SQ
2e760 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65  LITE_ROW] before
2e770 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
2e780 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
2e790 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2e7a0 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73    Failure to res
2e7b0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
2e7c0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
2e7d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2e7e0 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75  et()] would resu
2e7f0 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  lt in an [SQLITE
2e800 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20  _MISUSE] return 
2e810 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
2e820 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74  step().  But aft
2e830 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32  er version 3.6.2
2e840 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  3.1, sqlite3_ste
2e850 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
2e860 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2e870 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
2e880 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
2e890 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
2e8a0 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
2e8b0 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
2e8c0 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
2e8d0 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
2e8e0 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
2e8f0 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
2e900 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
2e910 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
2e920 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
2e930 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
2e940 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
2e950 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
2e960 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
2e970 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2e980 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
2e990 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
2e9a0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
2e9b0 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
2e9c0 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
2e9d0 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
2e9e0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2e9f0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2ea00 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
2ea10 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
2ea20 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
2ea30 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
2ea40 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
2ea50 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
2ea60 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
2ea70 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
2ea80 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
2ea90 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
2eaa0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
2eab0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2eac0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
2ead0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
2eae0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2eaf0 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
2eb00 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
2eb10 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
2eb20 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
2eb30 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
2eb40 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
2eb50 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
2eb60 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2eb70 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
2eb80 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
2eb90 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
2eba0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
2ebb0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
2ebc0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2ebd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2ebe0 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
2ebf0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
2ec00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2ec10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2ec20 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
2ec30 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
2ec40 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
2ec50 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2ec60 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
2ec70 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
2ec80 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
2ec90 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
2eca0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2ecb0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53  ecommended..*/.S
2ecc0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2ecd0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2ece0 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
2ecf0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2ed00 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2ed10 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2ed20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20  a result set.** 
2ed30 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2ed40 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2ed50 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2ed60 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
2ed70 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2ed80 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2ed90 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
2eda0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2edb0 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
2edc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2edd0 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
2ede0 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
2edf0 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
2ee00 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
2ee10 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
2ee20 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2ee30 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
2ee40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
2ee50 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
2ee60 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
2ee70 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2ee80 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
2ee90 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2eea0 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2eeb0 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
2eec0 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
2eed0 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
2eee0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2eef0 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
2ef00 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
2ef10 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
2ef20 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
2ef30 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
2ef40 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
2ef50 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2ef60 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
2ef70 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
2ef80 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
2ef90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2efa0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
2efb0 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
2efc0 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
2efd0 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
2efe0 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
2eff0 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
2f000 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
2f010 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
2f020 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
2f030 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
2f040 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
2f050 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
2f060 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2f070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2f080 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
2f090 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2f0a0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2f0b0 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
2f0c0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2f0d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f0e0 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
2f0f0 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
2f100 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
2f110 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
2f120 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
2f130 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
2f140 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
2f150 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
2f160 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2f170 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2f180 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
2f190 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
2f1a0 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
2f1b0 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
2f1c0 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
2f1d0 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
2f1e0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2f1f0 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
2f200 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
2f210 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
2f220 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
2f230 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
2f240 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
2f250 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2f260 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
2f270 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
2f280 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
2f290 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
2f2a0 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
2f2b0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
2f2c0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
2f2d0 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
2f2e0 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
2f2f0 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
2f300 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2f310 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
2f320 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
2f330 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
2f340 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
2f350 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f360 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
2f370 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
2f380 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
2f390 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
2f3a0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
2f3b0 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
2f3c0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
2f3d0 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
2f3e0 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
2f3f0 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
2f400 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
2f410 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2f420 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
2f430 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2f440 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2f450 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
2f460 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
2f470 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
2f480 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
2f490 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
2f4a0 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
2f4b0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
2f4c0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
2f4d0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
2f4e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2f4f0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
2f500 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
2f510 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2f520 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
2f530 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
2f540 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2f550 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
2f560 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
2f570 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
2f580 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2f590 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
2f5a0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
2f5b0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
2f5c0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
2f5d0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2f5e0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2f5f0 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
2f600 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
2f610 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2f620 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2f630 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
2f640 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2f650 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2f660 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
2f670 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2f680 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
2f690 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
2f6a0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
2f6b0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
2f6c0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2f6d0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
2f6e0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2f6f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2f700 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
2f710 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
2f720 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
2f730 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2f740 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
2f750 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
2f760 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
2f770 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
2f780 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2f790 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
2f7a0 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
2f7b0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
2f7c0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2f7d0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
2f7e0 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
2f7f0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2f800 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2f810 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
2f820 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2f830 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
2f840 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
2f850 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
2f860 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2f870 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
2f880 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2f890 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2f8a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2f8b0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
2f8c0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
2f8d0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
2f8e0 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
2f8f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2f900 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
2f910 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2f920 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2f930 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f940 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
2f950 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2f960 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
2f970 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2f980 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
2f990 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
2f9a0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
2f9b0 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
2f9c0 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
2f9d0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2f9e0 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
2f9f0 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
2fa00 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
2fa10 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
2fa20 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
2fa30 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
2fa40 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2fa50 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
2fa60 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
2fa70 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
2fa80 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
2fa90 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
2faa0 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
2fab0 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
2fac0 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
2fad0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
2fae0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2faf0 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
2fb00 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
2fb10 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2fb20 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
2fb30 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
2fb40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2fb50 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
2fb60 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2fb70 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
2fb80 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2fb90 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
2fba0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2fbb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2fbc0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2fbd0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2fbe0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2fbf0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2fc00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2fc10 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
2fc20 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2fc30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2fc40 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2fc50 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2fc60 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
2fc70 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2fc80 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2fc90 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2fca0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2fcb0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2fcc0 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
2fcd0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
2fce0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
2fcf0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
2fd00 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
2fd10 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2fd20 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2fd30 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2fd40 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2fd50 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2fd60 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2fd70 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73  _bytes() returns
2fd80 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   zero..**.** ^If
2fd90 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2fda0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20   BLOB or UTF-16 
2fdb0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2fdc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fdd0 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74  ytes16().** rout
2fde0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2fdf0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2fe00 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2fe10 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2fe20 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2fe30 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65  TF-8 string, the
2fe40 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2fe50 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65  _bytes16() conve
2fe60 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
2fe70 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20  g to UTF-16 and 
2fe80 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2fe90 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2fea0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2feb0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2fec0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2fed0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2fee0 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  16() uses.** [sq
2fef0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2ff00 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
2ff10 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
2ff20 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72  -16 string and r
2ff30 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2ff40 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2ff50 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2ff60 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2ff70 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
2ff80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ff90 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a  es16() returns z
2ffa0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ero..**.** ^The 
2ffb0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2ffc0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
2ffd0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
2ffe0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2fff0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64  umn_bytes16()] d
30000 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  o not include th
30010 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
30020 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  rs at the end.**
30030 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
30040 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
30050 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
30060 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
30070 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
30080 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
30090 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
300a0 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20   are the number 
300b0 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
300c0 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
300d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
300e0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
300f0 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
30100 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
30110 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
30120 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30130 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
30140 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
30150 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  e always zero-te
30160 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
30170 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
30180 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
30190 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
301a0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
301b0 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  B is a NULL poin
301c0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61  ter..**.** <b>Wa
301d0 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20  rning:</b> ^The 
301e0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
301f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
30200 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
30210 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
30220 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30230 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d   object.  In a m
30240 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e 76  ultithreaded env
30250 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20  ironment,.** an 
30260 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
30270 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
30280 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
30290 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a  d safely with.**
302a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
302b0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
302c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
302d0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
302e0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
302f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30300 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
30310 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
30320 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
30330 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
30340 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
30350 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
30360 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
30370 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
30380 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30390 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
303a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
303b0 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76  es()], the behav
303c0 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ior is not threa
303d0 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dsafe..**.** The
303e0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
303f0 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
30400 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
30410 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
30420 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
30430 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
30440 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
30450 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
30460 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
30470 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
30480 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
30490 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
304a0 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
304b0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
304c0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
304d0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
304e0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
304f0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
30500 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
30510 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
30520 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
30530 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
30540 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
30550 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
30560 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
30570 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
30580 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
30590 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
305a0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
305b0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
305c0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
305d0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
305e0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
305f0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
30600 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
30610 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
30620 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
30630 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
30640 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
30650 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
30660 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
30670 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
30680 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
30690 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
306a0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
306b0 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
306c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
306d0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
306e0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
306f0 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
30700 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
30710 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
30720 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
30730 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
30740 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
30750 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
30760 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
30770 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
30780 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
30790 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
307a0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
307b0 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
307c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
307d0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
307e0 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  B    <td> [CAST]
307f0 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e   to BLOB.** <tr>
30800 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
30810 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
30820 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
30830 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
30840 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
30850 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
30860 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
30870 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
30880 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
30890 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
308a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
308b0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
308c0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
308d0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
308e0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
308f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
30900 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
30910 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  L.** <tr><td>  B
30920 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
30930 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
30940 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
30950 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
30960 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
30970 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
30980 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
30990 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
309a0 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
309b0 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
309c0 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
309d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
309e0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
309f0 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
30a00 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
30a10 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
30a20 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
30a30 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
30a40 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
30a50 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
30a60 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
30a70 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
30a80 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
30a90 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
30aa0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
30ab0 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
30ac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
30ad0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
30ae0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30af0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
30b00 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
30b10 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
30b20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
30b30 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
30b40 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
30b50 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
30b60 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
30b70 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
30b80 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
30b90 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
30ba0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
30bb0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
30bc0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
30bd0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
30be0 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
30bf0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
30c00 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
30c10 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
30c20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30c30 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
30c40 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
30c50 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
30c60 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
30c70 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
30c80 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
30c90 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
30ca0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  l>.**.** ^Conver
30cb0 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
30cc0 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
30cd0 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
30ce0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
30cf0 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
30d00 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
30d10 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
30d20 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
30d30 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
30d40 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
30d50 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65  ior pointer refe
30d60 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65  rences will have
30d70 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
30d80 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
30d90 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
30da0 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
30db0 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
30dc0 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
30dd0 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
30de0 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
30df0 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
30e00 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
30e10 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
30e20 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
30e30 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
30e40 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
30e50 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
30e60 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
30e70 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
30e80 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
30e90 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
30ea0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
30eb0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
30ec0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
30ed0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
30ee0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
30ef0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30f00 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
30f10 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
30f20 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
30f30 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
30f40 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
30f50 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
30f60 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
30f70 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
30f80 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
30f90 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
30fa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
30fb0 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
30fc0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
30fd0 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
30fe0 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
30ff0 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
31000 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
31010 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
31020 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
31030 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31040 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
31050 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
31060 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
31070 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
31080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
31090 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
310a0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
310b0 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
310c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
310d0 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
310e0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
310f0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
31100 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
31110 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
31120 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
31130 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
31140 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
31150 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
31160 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
31170 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
31180 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
31190 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
311a0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
311b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
311c0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
311d0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
311e0 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
311f0 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
31200 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
31210 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
31220 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
31230 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65  .  Do <em>not</e
31240 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  m> pass the poin
31250 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
31260 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
31270 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
31280 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
31290 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
312a0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
312b0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
312c0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
312d0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
312e0 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
312f0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
31300 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
31310 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
31320 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
31330 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
31340 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
31350 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
31360 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
31370 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
31380 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
31390 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
313a0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
313b0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
313c0 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
313d0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
313e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
313f0 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
31400 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
31410 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
31420 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31430 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
31440 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
31450 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
31460 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
31470 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
31480 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
31490 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
314a0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
314b0 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
314c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
314d0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64  l);.SQLITE_API d
314e0 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44  ouble SQLITE_STD
314f0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
31500 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
31510 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
31520 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
31530 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
31540 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
31550 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
31560 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
31570 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
31580 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f  e3_int64 SQLITE_
31590 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
315a0 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
315b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
315c0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
315d0 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  I const unsigned
315e0 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
315f0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
31600 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
31610 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
31620 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  l);.SQLITE_API c
31630 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
31640 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
31650 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
31660 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31670 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
31680 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
31690 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
316a0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
316b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
316c0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
316d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
316e0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
316f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
31700 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
31710 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
31720 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
31730 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
31740 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
31750 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52  ct.** DESTRUCTOR
31760 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31770 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31780 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
31790 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
317a0 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
317b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
317c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
317d0 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
317e0 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
317f0 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
31800 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
31810 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
31820 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
31830 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
31840 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31850 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
31860 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
31870 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
31880 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
31890 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
318a0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
318b0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
318c0 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
318d0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
318e0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
318f0 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
31900 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31910 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
31920 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
31930 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
31940 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
31950 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
31960 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31970 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
31980 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
31990 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
319a0 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
319b0 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
319c0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
319d0 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
319e0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
319f0 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
31a00 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
31a10 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
31a20 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
31a30 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
31a40 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
31a50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
31a60 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
31a70 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
31a80 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
31a90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
31aa0 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
31ab0 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
31ac0 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
31ad0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
31ae0 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
31af0 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
31b00 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
31b10 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
31b20 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
31b30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
31b40 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
31b50 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
31b60 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
31b70 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
31b80 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
31b90 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
31ba0 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
31bb0 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
31bc0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
31bd0 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
31be0 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
31bf0 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
31c00 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
31c10 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66  TDCALL sqlite3_f
31c20 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
31c30 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
31c40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
31c50 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
31c60 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
31c70 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31c80 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54  te3_stmt.**.** T
31c90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
31ca0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
31cb0 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
31cc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31cd0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
31ce0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
31cf0 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
31d00 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
31d10 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
31d20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
31d30 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
31d40 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
31d50 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
31d60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
31d70 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
31d80 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
31d90 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
31da0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
31db0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
31dc0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
31dd0 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
31de0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
31df0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
31e00 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
31e10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31e20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
31e30 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
31e40 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
31e50 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
31e60 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
31e70 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
31e80 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
31e90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
31ea0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
31eb0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
31ec0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
31ed0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
31ee0 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
31ef0 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
31f00 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
31f10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
31f20 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
31f30 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
31f40 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
31f50 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
31f60 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
31f70 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
31f80 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
31f90 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
31fa0 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
31fb0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
31fc0 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
31fd0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
31fe0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
31ff0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
32000 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
32010 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
32020 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
32030 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
32040 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
32050 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
32060 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c  ement] S..*/.SQL
32070 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
32080 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
32090 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
320a0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
320b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
320c0 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
320d0 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
320e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
320f0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
32100 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
32110 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
32120 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
32130 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
32140 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
32150 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
32160 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
32170 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
32180 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
32190 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
321a0 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
321b0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
321c0 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
321d0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
321e0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
321f0 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
32200 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
32210 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
32220 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
32230 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
32240 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
32250 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
32260 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
32270 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
32280 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
32290 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
322a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
322b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
322c0 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
322d0 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
322e0 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
322f0 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
32300 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
32310 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
32320 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
32330 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
32340 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
32350 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
32360 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
32370 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
32380 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
32390 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
323a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
323b0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
323c0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
323d0 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
323e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
323f0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
32400 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
32410 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
32420 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
32430 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
32440 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
32450 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
32460 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32470 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
32480 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
32490 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
324a0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
324b0 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
324c0 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
324d0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
324e0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
324f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
32500 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
32510 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
32520 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
32530 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
32540 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
32550 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
32560 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
32570 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
32580 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
32590 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
325a0 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
325b0 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
325c0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
325d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
325e0 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
325f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
32600 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
32610 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
32620 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
32630 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
32640 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
32650 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
32660 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
32670 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
32680 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
32690 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
326a0 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
326b0 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
326c0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
326d0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
326e0 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
326f0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
32700 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
32710 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
32720 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
32730 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
32740 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
32750 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
32760 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
32770 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
32780 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
32790 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
327a0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
327b0 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
327c0 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
327d0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
327e0 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20  should set this 
327f0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
32800 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
32810 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   if the function
32820 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32830 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c  invokes .** [sql
32840 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
32850 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6le()] on an inp
32860 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ut, or [SQLITE_U
32870 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a  TF16BE] if the.*
32880 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
32890 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65   invokes [sqlite
328a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
328b0 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
328c0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   or.** [SQLITE_U
328d0 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65  TF16] if [sqlite
328e0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
328f0 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53  ] is used, or [S
32900 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f  QLITE_UTF8].** o
32910 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20  therwise.  ^The 
32920 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
32930 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
32940 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
32950 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66  es using.** diff
32960 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20  erent preferred 
32970 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20  text encodings, 
32980 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69  with different i
32990 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
329a0 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64  or.** each encod
329b0 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75  ing..** ^When mu
329c0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
329d0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
329e0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
329f0 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
32a00 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
32a10 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
32a20 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
32a30 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
32a40 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
32a50 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
32a60 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e  meter may option
32a70 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74  ally be ORed wit
32a80 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  h [SQLITE_DETERM
32a90 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73  INISTIC].** to s
32aa0 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66  ignal that the f
32ab0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77  unction will alw
32ac0 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
32ad0 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e  ame result given
32ae0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70  .** the same inp
32af0 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e  uts within a sin
32b00 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
32b10 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e  t.  Most SQL fun
32b20 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65  ctions are.** de
32b30 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
32b40 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64  e built-in [rand
32b50 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  om()] SQL functi
32b60 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  on is an example
32b70 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   of a.** functio
32b80 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65  n that is not de
32b90 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
32ba0 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70  e SQLite query p
32bb0 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74  lanner is able t
32bc0 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64  o.** perform add
32bd0 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61  itional optimiza
32be0 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69  tions on determi
32bf0 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73  nistic functions
32c00 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74  , so use.** of t
32c10 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  he [SQLITE_DETER
32c20 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69  MINISTIC] flag i
32c30 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68  s recommended wh
32c40 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a  ere possible..**
32c50 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
32c60 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
32c70 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
32c80 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
32c90 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
32ca0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
32cb0 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
32cc0 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
32cd0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
32ce0 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
32cf0 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
32d00 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
32d10 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
32d20 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
32d30 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
32d40 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
32d50 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
32d60 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
32d70 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
32d80 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
32d90 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
32da0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
32db0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
32dc0 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
32dd0 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
32de0 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
32df0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
32e00 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
32e10 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
32e20 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
32e30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
32e40 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
32e50 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
32e60 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
32e70 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
32e80 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
32e90 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
32ea0 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
32eb0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
32ec0 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
32ed0 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
32ee0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
32ef0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
32f00 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
32f10 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
32f20 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
32f30 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
32f40 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
32f50 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
32f60 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
32f70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
32f80 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
32f90 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
32fa0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
32fb0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
32fc0 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
32fd0 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
32fe0 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
32ff0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
33000 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
33010 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
33020 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
33030 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
33040 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
33050 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
33060 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
33070 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
33080 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
33090 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
330a0 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
330b0 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
330c0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
330d0 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
330e0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
330f0 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
33100 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
33110 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
33120 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
33130 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
33140 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
33150 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
33160 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
33170 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
33180 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
33190 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
331a0 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
331b0 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
331c0 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
331d0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
331e0 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
331f0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
33200 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
33210 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
33220 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
33230 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
33240 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
33250 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
33260 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
33270 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
33280 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33290 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
332a0 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
332b0 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
332c0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
332d0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
332e0 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
332f0 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
33300 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
33310 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
33320 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
33330 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
33340 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
33350 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
33360 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
33370 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
33380 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
33390 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
333a0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
333b0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
333c0 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
333d0 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
333e0 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
333f0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
33400 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
33410 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
33420 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
33430 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
33440 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
33450 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
33460 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
33470 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
33480 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33490 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
334a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
334b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
334c0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
334d0 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
334e0 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
334f0 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
33500 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
33510 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
33520 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
33530 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
33540 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
33550 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
33560 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
33570 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
33580 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
33590 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
335a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
335b0 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
335c0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
335d0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
335e0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
335f0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
33600 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
33610 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
33620 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33630 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
33640 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
33650 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
33660 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
33670 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
33680 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
33690 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
336a0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
336b0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
336c0 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  L sqlite3_create
336d0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
336e0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
336f0 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
33700 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
33710 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
33720 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
33730 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
33740 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
33750 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
33760 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
33770 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
33780 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
33790 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
337a0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
337b0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
337c0 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  t*).);.SQLITE_AP
337d0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
337e0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65  CALL sqlite3_cre
337f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
33800 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
33810 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
33820 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
33830 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
33840 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
33850 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
33860 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
33870 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
33880 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
33890 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
338a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
338b0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
338c0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
338d0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
338e0 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28  ntext*),.  void(
338f0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
33900 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
33910 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
33920 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
33930 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
33940 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
33950 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
33960 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
33970 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
33980 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
33990 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
339a0 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
339b0 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    1    /* IMP: R
339c0 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a  -37514-35566 */.
339d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
339e0 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 20  TF16LE        2 
339f0 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33     /* IMP: R-033
33a00 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66  71-37637 */.#def
33a10 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
33a20 42 45 20 20 20 20 20 20 20 20 33 20 20 20 20 2f  BE        3    /
33a30 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33  * IMP: R-51971-3
33a40 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20  4154 */.#define 
33a50 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
33a60 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
33a70 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
33a80 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
33a90 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
33aa0 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70       5    /* Dep
33ab0 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69  recated */.#defi
33ac0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
33ad0 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
33ae0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33af0 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
33b00 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
33b10 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67  F: Function Flag
33b20 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
33b30 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f  nstants may be O
33b40 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74  Red together wit
33b50 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
33b60 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72  E_UTF8 | preferr
33b70 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
33b80 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  ] as the fourth 
33b90 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
33ba0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33bb0 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  unction()], [sql
33bc0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33bd0 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
33be0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33bf0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e  _function_v2()].
33c00 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
33c10 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
33c20 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a      0x800../*.**
33c30 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
33c40 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a  cated Functions.
33c50 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
33c60 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
33c70 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61  ons are [depreca
33c80 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20  ted].  In order 
33c90 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
33ca0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
33cb0 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
33cc0 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75  r code, these fu
33cd0 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  nctions continue
33ce0 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f   .** to be suppo
33cf0 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20  rted.  However, 
33d00 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
33d10 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
33d20 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
33d30 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
33d40 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72   encourage progr
33d50 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a  ammers to avoid.
33d60 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ** these functio
33d70 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20  ns, we will not 
33d80 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65  explain what the
33d90 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
33da0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
33db0 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41  RECATED.SQLITE_A
33dc0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
33dd0 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f  ATED int SQLITE_
33de0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
33df0 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
33e00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33e10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
33e20 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
33e30 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
33e40 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  LL sqlite3_expir
33e50 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
33e60 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
33e70 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
33e80 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
33e90 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  LL sqlite3_trans
33ea0 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
33eb0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
33ec0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
33ed0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
33ee0 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c  PRECATED int SQL
33ef0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
33f00 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
33f10 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
33f20 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
33f30 45 43 41 54 45 44 20 76 6f 69 64 20 53 51 4c 49  ECATED void SQLI
33f40 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
33f50 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
33f60 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
33f70 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
33f80 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45  CATED int SQLITE
33f90 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
33fa0 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
33fb0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
33fc0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a  te3_int64,int),.
33fd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33fe0 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69        void*,sqli
33ff0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
34000 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
34010 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
34020 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
34030 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
34040 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  e.**.** The C-la
34050 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
34060 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
34070 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
34080 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
34090 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
340a0 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
340b0 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
340c0 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
340d0 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
340e0 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a  r aggregate.  .*
340f0 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
34100 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
34110 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
34120 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
34130 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
34140 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34150 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
34160 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34170 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
34180 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
34190 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
341a0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
341b0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
341c0 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
341d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
341e0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
341f0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
34200 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
34210 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
34220 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
34230 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
34240 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34250 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
34260 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
34270 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
34280 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
34290 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
342a0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
342b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
342c0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
342d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
342e0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
342f0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
34300 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34310 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
34320 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
34330 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
34340 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
34350 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
34360 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
34370 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
34380 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
34390 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
343a0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
343b0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
343c0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
343d0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
343e0 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e  hat these routin
343f0 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
34400 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
34410 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34420 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
34430 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
34440 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
34450 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
34460 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
34470 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34480 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
34490 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
344a0 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
344b0 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
344c0 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
344d0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
344e0 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
344f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34500 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
34510 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
34520 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
34530 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
34540 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
34550 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
34560 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
34570 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
34580 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
34590 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
345a0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
345b0 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
345c0 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
345d0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
345e0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
345f0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
34600 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
34610 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
34620 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
34630 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
34640 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
34650 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
34660 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
34670 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
34680 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
34690 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
346a0 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
346b0 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
346c0 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
346d0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
346e0 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
346f0 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
34700 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
34710 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
34720 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
34730 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
34740 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
34750 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
34760 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
34770 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
34780 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
34790 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
347a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
347b0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
347c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
347d0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
347e0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
347f0 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
34800 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
34810 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
34820 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
34830 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
34840 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
34850 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
34860 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
34870 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
34880 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
34890 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
348a0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
348b0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
348c0 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
348d0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
348e0 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
348f0 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
34900 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49  ameters..*/.SQLI
34910 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
34920 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
34930 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
34940 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c  blob(sqlite3_val
34950 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
34960 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
34970 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
34980 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
34990 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
349a0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
349b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
349c0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
349d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
349e0 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20  LITE_API double 
349f0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
34a00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
34a10 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
34a20 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
34a30 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
34a40 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
34a50 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
34a60 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
34a70 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53   sqlite3_int64 S
34a80 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
34a90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
34aa0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
34ab0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
34ac0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
34ad0 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
34ae0 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
34af0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
34b00 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
34b10 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
34b20 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
34b30 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
34b40 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34b50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
34b60 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
34b70 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
34b80 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
34b90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34ba0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
34bb0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
34bc0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
34bd0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
34be0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
34bf0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
34c00 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
34c10 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
34c20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34c30 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
34c40 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
34c50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
34c60 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
34c70 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
34c80 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70 79 20   CAPI3REF: Copy 
34c90 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56 61 6c  And Free SQL Val
34ca0 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
34cb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
34cc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34cd0 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74  value_dup(V) int
34ce0 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
34cf0 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
34d00 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
34d10 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74 75 72  ject D and retur
34d20 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
34d30 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 65  that copy.  ^The
34d40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34d50 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
34d60 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  a [protected sql
34d70 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34d80 63 74 20 65 76 65 6e 20 69 66 20 74 68 65 20 69  ct even if the i
34d90 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20  nput is not..** 
34da0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
34db0 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66  ue_dup(V) interf
34dc0 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ace returns NULL
34dd0 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72   if V is NULL or
34de0 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20   if a.** memory 
34df0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
34e00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34e10 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28  ite3_value_free(
34e20 56 29 20 69 6e 74 65 72 66 61 63 65 20 66 72 65  V) interface fre
34e30 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  es an [sqlite3_v
34e40 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
34e50 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
34e60 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
34e70 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20  3_value_dup()]. 
34e80 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55 4c 4c   ^If V is a NULL
34e90 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e   pointer.** then
34ea0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66   sqlite3_value_f
34eb0 72 65 65 28 56 29 20 69 73 20 61 20 68 61 72 6d  ree(V) is a harm
34ec0 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53  less no-op..*/.S
34ed0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
34ee0 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 73 71  _EXPERIMENTAL sq
34ef0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 53 51 4c  lite3_value *SQL
34f00 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
34f10 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f  te3_value_dup(co
34f20 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
34f30 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
34f40 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
34f50 54 41 4c 20 76 6f 69 64 20 53 51 4c 49 54 45 5f  TAL void SQLITE_
34f60 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
34f70 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74  value_free(sqlit
34f80 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
34f90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
34fa0 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
34fb0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
34fc0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
34fd0 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
34fe0 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
34ff0 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
35000 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
35010 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
35020 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
35030 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
35040 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
35050 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
35060 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
35070 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
35080 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
35090 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
350a0 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
350b0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
350c0 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
350d0 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
350e0 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
350f0 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
35100 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
35110 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
35120 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
35130 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
35140 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
35150 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35160 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
35170 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
35180 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
35190 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
351a0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
351b0 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
351c0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
351d0 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
351e0 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
351f0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
35200 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
35210 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
35220 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
35230 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
35240 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
35250 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
35260 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
35270 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
35280 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
35290 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
352a0 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
352b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
352c0 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
352d0 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
352e0 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
352f0 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
35300 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
35310 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
35320 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
35330 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
35340 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
35350 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
35360 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35370 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
35380 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
35390 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
353a0 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68  L pointer .** wh
353b0 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20  en first called 
353c0 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  if N is less tha
353d0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
353e0 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  ro or if a memor
353f0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72  y.** allocate er
35400 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
35410 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
35420 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
35430 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
35440 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
35450 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
35460 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
35470 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
35480 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
35490 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
354a0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
354b0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
354c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
354d0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
354e0 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
354f0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
35500 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
35510 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
35520 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
35530 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68  ocation.)^  With
35540 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  in the xFinal ca
35550 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75  llback, it is cu
35560 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a  stomary to set.*
35570 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74  * N=0 in calls t
35580 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
35590 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
355a0 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20   so that no .** 
355b0 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79  pointless memory
355c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63   allocations occ
355d0 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ur..**.** ^SQLit
355e0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
355f0 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
35600 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
35610 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
35620 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
35630 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
35640 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
35650 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
35660 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
35670 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
35680 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
35690 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
356a0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
356b0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
356c0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
356d0 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
356e0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
356f0 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
35700 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
35710 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
35720 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
35730 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
35740 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
35750 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
35760 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
35770 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
35780 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
35790 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51  ITE_API void *SQ
357a0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
357b0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
357c0 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
357d0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
357e0 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
357f0 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
35800 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
35810 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
35820 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
35830 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
35840 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
35850 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
35860 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
35870 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
35880 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
35890 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
358a0 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
358b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
358c0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
358d0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
358e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
358f0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
35900 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
35910 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
35920 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
35930 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
35940 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
35950 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
35960 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
35970 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
35980 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35990 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
359a0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
359b0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
359c0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
359d0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
359e0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
359f0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
35a00 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
35a10 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
35a20 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  nctions.** METHO
35a30 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
35a40 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  xt.**.** ^The sq
35a50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
35a60 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
35a70 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
35a80 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
35a90 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
35aa0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35ab0 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
35ac0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
35ad0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35ae0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
35af0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
35b00 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
35b10 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
35b20 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
35b30 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
35b40 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
35b50 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  function..*/.SQL
35b60 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20  ITE_API sqlite3 
35b70 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
35b80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
35b90 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
35ba0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
35bb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
35bc0 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
35bd0 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Data.** METHOD:
35be0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
35bf0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
35c00 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
35c10 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65  ed by (non-aggre
35c20 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69  gate) SQL functi
35c30 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
35c40 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
35c50 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
35c60 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
35c70 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
35c80 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
35c90 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
35ca0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
35cb0 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
35cc0 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
35cd0 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
35ce0 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
35cf0 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
35d00 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
35d10 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20    An example.** 
35d20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69  of where this mi
35d30 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73  ght be useful is
35d40 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78   in a regular-ex
35d50 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
35d60 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  g.** function. T
35d70 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
35d80 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
35d90 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
35da0 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a  n be stored as.*
35db0 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
35dc0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
35dd0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20  attern string.  
35de0 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67  .** Then as long
35df0 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20   as the pattern 
35e00 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74  string remains t
35e10 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20  he same,.** the 
35e20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
35e30 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
35e40 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
35e50 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
35e60 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
35e70 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
35e80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
35e90 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
35ea0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
35eb0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
35ec0 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
35ed0 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
35ee0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35ef0 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
35f00 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
35f10 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
35f20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35f30 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
35f40 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
35f50 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
35f60 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
35f70 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
35f80 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  t, this sqlite3_
35f90 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
35fa0 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
35fb0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
35fc0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
35fd0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
35fe0 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72  a(C,N,P,X) inter
35ff0 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20  face saves P as 
36000 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
36010 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
36020 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
36030 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36040 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75  ction.  ^Subsequ
36050 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
36060 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
36070 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20  ata(C,N) return 
36080 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20  P from the most 
36090 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65  recent.** sqlite
360a0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
360b0 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74  N,P,X) call if t
360c0 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73  he metadata is s
360d0 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a  till valid or.**
360e0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74   NULL if the met
360f0 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64  adata has been d
36100 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66  iscarded..** ^Af
36110 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  ter each call to
36120 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
36130 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68  data(C,N,P,X) wh
36140 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c  ere X is not NUL
36150 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  L,.** SQLite wil
36160 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
36170 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
36180 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65   X with paramete
36190 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f  r P exactly.** o
361a0 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65  nce, when the me
361b0 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72  tadata is discar
361c0 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ded..** SQLite i
361d0 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72  s free to discar
361e0 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61  d the metadata a
361f0 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c  t any time, incl
36200 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c  uding: <ul>.** <
36210 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72  li> when the cor
36220 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
36230 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
36240 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  anges, or.** <li
36250 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  > when [sqlite3_
36260 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
36270 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
36280 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   is called for t
36290 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73  he.**      SQL s
362a0 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20  tatement, or.** 
362b0 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65  <li> when sqlite
362c0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
362d0 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e  is invoked again
362e0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72   on the same par
362f0 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c  ameter, or.** <l
36300 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72  i> during the or
36310 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73  iginal sqlite3_s
36320 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c  et_auxdata() cal
36330 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20  l when a memory 
36340 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74  .**      allocat
36350 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
36360 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  . </ul>)^.**.** 
36370 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75  Note the last bu
36380 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c  llet in particul
36390 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  ar.  The destruc
363a0 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c  tor X in .** sql
363b0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
363c0 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20  (C,N,P,X) might 
363d0 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69  be called immedi
363e0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68  ately, before th
363f0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  e.** sqlite3_set
36400 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
36410 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e  face even return
36420 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65  s.  Hence sqlite
36430 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a  3_set_auxdata().
36440 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  ** should be cal
36450 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64  led near the end
36460 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
36470 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36480 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  and the.** funct
36490 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
364a0 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61  on should not ma
364b0 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20  ke any use of P 
364c0 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33  after.** sqlite3
364d0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68  _set_auxdata() h
364e0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  as been called..
364f0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
36500 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
36510 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
36520 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
36530 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  s for.** functio
36540 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
36550 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69  t are compile-ti
36560 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e  me constants, in
36570 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a  cluding literal.
36580 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
36590 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65  arameters] and e
365a0 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f  xpressions compo
365b0 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  sed from the sam
365c0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  e.)^.**.** These
365d0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
365e0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
365f0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
36600 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
36610 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
36620 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
36630 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54  _API void *SQLIT
36640 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
36650 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
36660 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36670 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
36680 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53  PI void SQLITE_S
36690 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73  TDCALL sqlite3_s
366a0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
366b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
366c0 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
366d0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
366e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
366f0 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
36700 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
36710 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a  ctor Behavior.**
36720 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
36730 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
36740 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
36750 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
36760 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
36770 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
36780 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
36790 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
367a0 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65  ()].  ^If the de
367b0 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
367c0 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
367d0 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
367e0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
367f0 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
36800 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
36810 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
36820 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
36830 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
36840 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54  .  ^The.** SQLIT
36850 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
36860 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
36870 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
36880 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
36890 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
368a0 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
368b0 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
368c0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
368d0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
368e0 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
368f0 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
36900 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
36910 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
36920 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
36930 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
36940 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79  compilers..*/.ty
36950 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
36960 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
36970 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
36980 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
36990 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
369a0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
369b0 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
369c0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
369d0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
369e0 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
369f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36a00 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
36a10 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
36a20 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ction.** METHOD:
36a30 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
36a40 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
36a50 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
36a60 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
36a70 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
36a80 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
36a90 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
36aa0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
36ab0 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
36ac0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
36ad0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
36ae0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
36af0 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
36b00 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
36b10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
36b20 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
36b30 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
36b40 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69  he [parameter bi
36b50 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66  nding] family of
36b60 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  .** functions us
36b70 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ed to bind value
36b80 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
36b90 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
36ba0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
36bb0 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51  Refer to the [SQ
36bc0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63  L parameter] doc
36bd0 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
36be0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
36bf0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
36c00 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36c10 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
36c20 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
36c30 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
36c40 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36c50 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
36c60 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
36c70 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
36c80 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
36c90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
36ca0 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
36cb0 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
36cc0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
36cd0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
36ce0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36cf0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
36d00 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
36d10 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
36d20 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
36d30 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
36d40 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
36d50 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
36d60 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
36d70 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
36d80 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
36d90 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
36da0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
36db0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36dc0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
36dd0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
36de0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
36df0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
36e00 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36e10 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
36e20 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
36e30 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
36e40 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
36e50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36e60 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36e70 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
36e80 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
36e90 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
36ea0 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
36eb0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
36ec0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
36ed0 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ption..** ^SQLit
36ee0 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
36ef0 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
36f00 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
36f10 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
36f20 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
36f30 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
36f40 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
36f50 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
36f60 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
36f70 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65  ^SQLite interpre
36f80 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
36f90 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
36fa0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
36fb0 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
36fc0 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  F-8. ^SQLite.** 
36fd0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
36fe0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
36ff0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
37000 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
37010 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
37020 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20  order.  ^If the 
37030 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
37040 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
37050 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
37060 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37070 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
37080 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
37090 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
370a0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
370b0 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
370c0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
370d0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
370e0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
370f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
37100 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
37110 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
37120 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
37130 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
37140 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
37150 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
37160 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
37170 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
37180 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
37190 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
371a0 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ge..** ^The sqli
371b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
371c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
371d0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
371e0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
371f0 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20   a private copy 
37200 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
37210 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
37220 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
37230 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
37240 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
37250 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
37260 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
37270 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
37280 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
37290 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  m..** ^The sqlit
372a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
372b0 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
372c0 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
372d0 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
372e0 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
372f0 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
37300 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
37310 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74  on.  ^By default
37320 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
37330 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
37340 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75  ROR.  ^A subsequ
37350 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
37360 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37370 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
37380 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
37390 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72  ) resets the err
373a0 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54  or code to SQLIT
373b0 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e  E_ERROR..**.** ^
373c0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
373d0 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
373e0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
373f0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
37400 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69  ow an.** error i
37410 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
37420 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
37430 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
37440 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
37450 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37460 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
37470 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
37480 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
37490 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69  ow an.** error i
374a0 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
374b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
374c0 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
374d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
374e0 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72  sult_int() inter
374f0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
37500 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
37510 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37520 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
37530 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62  n to be the 32-b
37540 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
37550 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
37560 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
37570 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ment..** ^The sq
37580 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
37590 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
375a0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
375b0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
375c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
375d0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
375e0 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
375f0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
37600 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
37610 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
37620 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37630 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
37640 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
37650 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
37660 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
37670 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37680 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55  unction to be NU
37690 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
376a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
376b0 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  xt(), sqlite3_re
376c0 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a  sult_text16(),.*
376d0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
376e0 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64  _text16le(), and
376f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37700 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72  text16be() inter
37710 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65  faces.** set the
37720 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
37730 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37740 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
37750 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78  n to be.** a tex
37760 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  t string which i
37770 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  s represented as
37780 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e   UTF-8, UTF-16 n
37790 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
377a0 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
377b0 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le endian, or UT
377c0 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c  F-16 big endian,
377d0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
377e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
377f0 65 73 75 6c 74 5f 74 65 78 74 36 34 28 29 20 69  esult_text64() i
37800 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
37810 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
37820 66 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74  f an.** applicat
37830 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
37840 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 74 65 78  tion to be a tex
37850 74 20 73 74 72 69 6e 67 20 69 6e 20 61 6e 20 65  t string in an e
37860 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73 70 65 63 69  ncoding.** speci
37870 66 69 65 64 20 62 79 20 74 68 65 20 66 69 66 74  fied by the fift
37880 68 20 28 61 6e 64 20 6c 61 73 74 29 20 70 61 72  h (and last) par
37890 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 6d 75  ameter, which mu
378a0 73 74 20 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20  st be one.** of 
378b0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
378c0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b  SQLITE_UTF16], [
378d0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
378e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
378f0 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  6LE]..** ^SQLite
37900 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
37910 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
37920 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
37930 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
37940 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
37950 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
37960 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
37970 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
37980 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
37990 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
379a0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
379b0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
379c0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
379d0 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
379e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
379f0 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
37a00 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
37a10 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
37a20 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
37a30 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
37a40 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
37a50 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
37a60 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
37a70 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
37a80 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
37a90 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
37aa0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
37ab0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
37ac0 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
37ad0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37ae0 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
37af0 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20  result.  If the 
37b00 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
37b10 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
37b20 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62  hen it.** must b
37b30 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
37b40 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e  t into the strin
37b50 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  g where the NUL 
37b60 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
37b70 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68  .** appear if th
37b80 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e  e string where N
37b90 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  UL terminated.  
37ba0 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
37bb0 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69  cters occur.** i
37bc0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20  n the string at 
37bd0 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68  a byte offset th
37be0 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  at is less than 
37bf0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
37c00 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65   3rd.** paramete
37c10 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  r, then the resu
37c20 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c  lting string wil
37c30 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  l contain embedd
37c40 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a  ed NULs and the.
37c50 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  ** result of exp
37c60 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69  ressions operati
37c70 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69  ng on strings wi
37c80 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
37c90 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
37ca0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
37cb0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
37cc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37cd0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
37ce0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
37cf0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
37d00 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
37d10 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
37d20 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
37d30 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
37d40 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
37d50 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
37d60 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
37d70 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
37d80 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
37d90 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
37da0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
37db0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
37dc0 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
37dd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
37de0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
37df0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
37e00 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
37e10 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
37e20 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
37e30 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
37e40 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
37e50 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
37e60 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
37e70 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
37e80 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
37e90 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
37ea0 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
37eb0 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
37ec0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
37ed0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
37ee0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
37ef0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
37f00 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
37f10 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
37f20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
37f30 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
37f40 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
37f50 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
37f60 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
37f70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
37f80 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
37f90 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
37fa0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
37fb0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
37fc0 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
37fd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37fe0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
37ff0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
38000 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
38010 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
38020 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
38030 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 6f 66   to be a copy of
38040 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
38050 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
38060 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
38070 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
38080 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
38090 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
380a0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
380b0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
380c0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
380d0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
380e0 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
380f0 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
38100 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
38110 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
38120 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
38130 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
38140 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
38150 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
38160 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f  harm..** ^A [pro
38170 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
38180 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
38190 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
381a0 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
381b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
381c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
381d0 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
381e0 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
381f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
38200 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
38210 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
38220 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
38230 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
38240 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
38250 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
38260 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
38270 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
38280 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
38290 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
382a0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
382b0 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
382c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
382d0 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
382e0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
382f0 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
38300 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  I void SQLITE_ST
38310 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65  DCALL sqlite3_re
38320 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
38330 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
38340 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
38350 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
38360 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53  QLITE_API void S
38370 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
38380 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
38390 62 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  b64(sqlite3_cont
383a0 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ext*,const void*
383b0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
383c0 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
383d0 69 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f 69 64  ite3_uint64,void
383e0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
383f0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
38400 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
38410 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
38420 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
38430 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c  t*, double);.SQL
38440 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
38450 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
38460 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
38470 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38480 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
38490 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
384a0 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44   void SQLITE_STD
384b0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73  CALL sqlite3_res
384c0 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69  ult_error16(sqli
384d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
384e0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  nst void*, int);
384f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
38500 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
38510 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
38520 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
38530 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
38540 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53  QLITE_API void S
38550 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
38560 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
38570 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
38580 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
38590 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49  TE_API void SQLI
385a0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
385b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
385c0 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  code(sqlite3_con
385d0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  text*, int);.SQL
385e0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
385f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
38600 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
38610 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
38620 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
38630 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  I void SQLITE_ST
38640 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65  DCALL sqlite3_re
38650 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
38660 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
38670 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c  ite3_int64);.SQL
38680 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
38690 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
386a0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
386b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
386c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
386d0 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  id SQLITE_STDCAL
386e0 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  L sqlite3_result
386f0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
38700 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
38710 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
38720 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
38730 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
38740 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
38750 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34 28  3_result_text64(
38760 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
38770 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  , const char*,sq
38780 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
38790 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20