System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 313a3e4b4a675dc0ebdd3aa775918aba956d2963:


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 32 22 0a 23 64       "3.8.12".#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 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  012.#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 31 30 2d 30 38 20 31 37    "2015-10-08 17
1100: 3a 33 35 3a 35 31 20 64 66 39 65 66 36 31 66 31  :35:51 df9ef61f1
1110: 62 61 32 65 33 61 33 34 32 30 66 61 65 38 34 65  ba2e3a3420fae84e
1120: 33 65 61 61 32 65 30 65 32 33 35 62 63 32 38 22  3eaa2e0e235bc28"
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 65  ader, and thus e
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 65 6e  lication must en
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 49 4f 45 52 52 5f 56 4e   SQLITE_IOERR_VN
56c0: 4f 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ODE             
56d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
56e0: 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (27<<8)).#define
56f0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
5700: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
5710: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
5720: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5730: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
5740: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
5750: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5760: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5770: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53  ne SQLITE_BUSY_S
5780: 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20  NAPSHOT         
5790: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20    (SQLITE_BUSY  
57a0: 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66   |  (2<<8)).#def
57b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
57c0: 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20  PEN_NOTEMPDIR   
57d0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
57e0: 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  PEN | (1<<8)).#d
57f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5800: 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20  TOPEN_ISDIR     
5810: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5820: 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a  TOPEN | (2<<8)).
5830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5840: 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48  ANTOPEN_FULLPATH
5850: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5860: 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29  ANTOPEN | (3<<8)
5870: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5880: 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41  _CANTOPEN_CONVPA
5890: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
58a0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c  _CANTOPEN | (4<<
58b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58c0: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
58d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
58e0: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
58f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5900: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
5910: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
5920: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5930: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5940: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
5950: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
5960: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5970: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5980: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5990: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
59a0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
59b0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
59c0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
59d0: 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20  LY_DBMOVED      
59e0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
59f0: 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  LY | (4<<8)).#de
5a00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
5a10: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  T_ROLLBACK      
5a20: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52      (SQLITE_ABOR
5a30: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5a40: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5a50: 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20  RAINT_CHECK     
5a60: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5a70: 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RAINT | (1<<8)).
5a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5a90: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54  ONSTRAINT_COMMIT
5aa0: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43  HOOK   (SQLITE_C
5ab0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c  ONSTRAINT | (2<<
5ac0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5ad0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f  TE_CONSTRAINT_FO
5ae0: 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49  REIGNKEY   (SQLI
5af0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b00: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5b10: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b20: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28  T_FUNCTION     (
5b30: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b40: 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  T | (4<<8)).#def
5b50: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5b60: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20  RAINT_NOTNULL   
5b70: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5b80: 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a  RAINT | (5<<8)).
5b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5ba0: 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52  ONSTRAINT_PRIMAR
5bb0: 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  YKEY   (SQLITE_C
5bc0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c  ONSTRAINT | (6<<
5bd0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5be0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52  TE_CONSTRAINT_TR
5bf0: 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49  IGGER      (SQLI
5c00: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5c10: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
5c20: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c30: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28  T_UNIQUE       (
5c40: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c50: 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  T | (8<<8)).#def
5c60: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5c70: 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20  RAINT_VTAB      
5c80: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5c90: 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a  RAINT | (9<<8)).
5ca0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5cb0: 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20  ONSTRAINT_ROWID 
5cc0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5cd0: 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c  ONSTRAINT |(10<<
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 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49  R_WAL      (SQLI
5d10: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c  TE_NOTICE | (1<<
5d20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d30: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5d40: 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49  R_ROLLBACK (SQLI
5d50: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c  TE_NOTICE | (2<<
5d60: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d70: 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49  TE_WARNING_AUTOI
5d80: 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49  NDEX       (SQLI
5d90: 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c  TE_WARNING | (1<
5da0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5db0: 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20 20  ITE_AUTH_USER   
5dc0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5dd0: 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38  ITE_AUTH | (1<<8
5de0: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
5df0: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
5e00: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
5e10: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62  ns.**.** These b
5e20: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  it values are in
5e30: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
5e40: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72  n the.** 3rd par
5e50: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5e60: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5e70: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a  ] interface and.
5e80: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61  ** in the 4th pa
5e90: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
5ea0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
5eb0: 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64  n] method..*/.#d
5ec0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5ed0: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
5ee0: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f     0x00000001  /
5ef0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5f00: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5f20: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
5f30: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f     0x00000002  /
5f40: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5f50: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5f60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5f70: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
5f80: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f     0x00000004  /
5f90: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5fa0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5fb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5fc0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
5fd0: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f     0x00000008  /
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 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
6010: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f     0x00000010  /
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 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20  N_AUTOPROXY     
6050: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f     0x00000020  /
6060: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6080: 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20  N_URI           
6090: 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f     0x00000040  /
60a0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
60b0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
60c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
60d0: 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20  N_MEMORY        
60e0: 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f     0x00000080  /
60f0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6100: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6120: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
6130: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f     0x00000100  /
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 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
6170: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f     0x00000200  /
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 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
61b0: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f     0x00000400  /
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 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
61f0: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f     0x00000800  /
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 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
6230: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f     0x00001000  /
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 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
6270: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f     0x00002000  /
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 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
62b0: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f     0x00004000  /
62c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
62d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
62e0: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20  N_NOMUTEX       
62f0: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f     0x00008000  /
6300: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6310: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6320: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6330: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20  N_FULLMUTEX     
6340: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f     0x00010000  /
6350: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6360: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6380: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  N_SHAREDCACHE   
6390: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f     0x00020000  /
63a0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
63b0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
63c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
63d0: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20  N_PRIVATECACHE  
63e0: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f     0x00040000  /
63f0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6400: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6410: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6420: 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  N_WAL           
6430: 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f     0x00080000  /
6440: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  * VFS only */../
6450: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20  * Reserved:     
6460: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6470: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a      0x00F00000 *
6480: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
6490: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63  F: Device Charac
64a0: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  teristics.**.** 
64b0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
64c0: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
64d0: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  d of the [sqlite
64e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
64f0: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20   object returns 
6500: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
6510: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20   is a vector of 
6520: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
6530: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
6540: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
6550: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
6560: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
6570: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
6580: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
6590: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
65a0: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
65b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
65c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
65d0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
65e0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
65f0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
6600: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6610: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6620: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
6630: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
6640: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
6650: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
6660: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
6670: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
6680: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
6690: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
66a0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
66b0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
66c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
66d0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
66e0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
66f0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6700: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
6710: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6720: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
6730: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
6740: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
6750: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
6760: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
6770: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6780: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
6790: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
67a0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
67b0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
67c0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
67d0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
67e0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54   to xWrite().  T
67f0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6800: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
6810: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61  ITE property mea
6820: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72  ns that.** after
6830: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e   reboot followin
6840: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77  g a crash or pow
6850: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c  er loss, the onl
6860: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20  y bytes in a.** 
6870: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77  file that were w
6880: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70  ritten at the ap
6890: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20  plication level 
68a0: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67  might have chang
68b0: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61  ed.** and that a
68c0: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65  djacent bytes, e
68d0: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e  ven bytes within
68e0: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72   the same sector
68f0: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65   are.** guarante
6900: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67  ed to be unchang
6910: 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ed.  The SQLITE_
6920: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
6930: 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66  E_WHEN_OPEN.** f
6940: 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61  lag indicate tha
6950: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  t a file cannot 
6960: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  be deleted when 
6970: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51  open.  The.** SQ
6980: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6990: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61  ABLE flag indica
69a0: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c  tes that the fil
69b0: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d  e is on.** read-
69c0: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63  only media and c
69d0: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
69e0: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73   even by process
69f0: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61  es with.** eleva
6a00: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a  ted privileges..
6a10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6a20: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
6a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6a40: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
6a50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6a60: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
6a70: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
6a80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a90: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
6aa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6ab0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
6ac0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6ad0: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
6ae0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
6af0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6b00: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
6b10: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b20: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
6b30: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6b40: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
6b50: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
6b60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b70: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
6b80: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b90: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
6ba0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6bb0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6bc0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
6bd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6be0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
6bf0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6c00: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6c10: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6c20: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
6c30: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
6c40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6c50: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
6c60: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
6c70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c80: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6c90: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
6ca0: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
6cb0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6cc0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
6cd0: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
6ce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6cf0: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
6d00: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6d10: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  2000../*.** CAPI
6d20: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
6d30: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
6d40: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
6d50: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
6d60: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6d70: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6d80: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6d90: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6da0: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6db0: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
6dc0: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
6dd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
6de0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6df0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
6e00: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
6e10: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6e20: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
6e30: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
6e40: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
6e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6e60: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6e70: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6e80: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
6e90: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
6ea0: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
6eb0: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
6ec0: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
6ed0: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
6ee0: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
6ef0: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
6f00: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6f10: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
6f20: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
6f30: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6f40: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6f50: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
6f60: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
6f70: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6f80: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
6f90: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
6fa0: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
6fb0: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
6fc0: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
6fd0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
6fe0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
6ff0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
7000: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
7010: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
7020: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
7030: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
7040: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
7050: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
7060: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
7070: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
7080: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
7090: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
70a0: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
70b0: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
70c0: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
70d0: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
70e0: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
70f0: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
7100: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7110: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
7120: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
7130: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
7140: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
7150: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
7160: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
7170: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
7180: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
7190: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
71a0: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
71b0: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
71c0: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
71d0: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
71e0: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
71f0: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
7200: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
7210: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
7220: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
7230: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
7240: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
7250: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
7260: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
7270: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
7280: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
7290: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
72a0: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
72b0: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
72c0: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
72d0: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
72e0: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
72f0: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
7300: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
7310: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
7320: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
7330: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
7340: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
7350: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
7360: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
7370: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
7380: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
7390: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
73a0: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
73b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
73c0: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
73d0: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
73e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
73f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
7400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7410: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
7420: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
7430: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7440: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
7450: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
7460: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
7470: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
7480: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
7490: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
74a0: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
74b0: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
74c0: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
74d0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
74e0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
74f0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
7500: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
7510: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
7520: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
7530: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
7540: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
7550: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
7560: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
7570: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7580: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
7590: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
75a0: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
75b0: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
75c0: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
75d0: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
75e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
75f0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
7600: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
7610: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
7620: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
7630: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
7640: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
7650: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
7660: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
7670: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7680: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
7690: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
76a0: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
76b0: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
76c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
76d0: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
76e0: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
76f0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7700: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
7710: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
7720: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
7730: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
7740: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
7750: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
7760: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
7770: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
7780: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
7790: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
77a0: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
77b0: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
77c0: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
77d0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
77e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
77f0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
7800: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7810: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
7820: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
7830: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7840: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
7850: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
7860: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
7870: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
7880: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
7890: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
78a0: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
78b0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
78c0: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
78d0: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
78e0: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
78f0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
7900: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
7910: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
7920: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
7930: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
7940: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
7950: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
7960: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7970: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
7980: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
7990: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
79a0: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
79b0: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
79c0: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
79d0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
79e0: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
79f0: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
7a00: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
7a10: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
7a20: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
7a30: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
7a40: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
7a50: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
7a60: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
7a70: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7a80: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
7a90: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
7aa0: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
7ab0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
7ac0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
7ad0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
7ae0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
7af0: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
7b00: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7b10: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7b20: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
7b30: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7b40: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7b50: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7b60: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7b70: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7b80: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
7b90: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7ba0: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
7bb0: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
7bc0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
7bd0: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
7be0: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
7bf0: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
7c00: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
7c10: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
7c20: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
7c30: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
7c40: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
7c50: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
7c60: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
7c70: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
7c80: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
7c90: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
7ca0: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
7cb0: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
7cc0: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
7cd0: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
7ce0: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
7cf0: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
7d00: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
7d10: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
7d20: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
7d30: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
7d40: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
7d50: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
7d60: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
7d70: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
7d80: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
7d90: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
7da0: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
7db0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
7dc0: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
7dd0: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
7de0: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
7df0: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
7e00: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
7e10: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
7e20: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
7e30: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
7e40: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
7e50: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
7e60: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
7e70: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
7e80: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
7e90: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
7ea0: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
7eb0: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
7ec0: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
7ed0: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
7ee0: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
7ef0: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
7f00: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
7f10: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
7f20: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
7f30: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
7f40: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
7f50: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
7f60: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
7f70: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
7f80: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
7f90: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
7fa0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
7fb0: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f  odes | list of o
7fc0: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
7fd0: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
7fe0: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
7ff0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
8000: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
8010: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
8020: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
8030: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
8040: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
8050: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
8060: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
8070: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
8080: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
8090: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
80a0: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
80b0: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
80c0: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
80d0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
80e0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
80f0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
8100: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
8110: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
8120: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
8130: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
8140: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
8150: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
8160: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
8170: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
8180: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
8190: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
81a0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
81b0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
81c0: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
81d0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
81e0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
81f0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
8200: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
8210: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8220: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
8230: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8240: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
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 31 4b 5d 0a  IOCAP_ATOMIC1K].
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 32 4b 5d 0a  IOCAP_ATOMIC2K].
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 34 4b 5d 0a  IOCAP_ATOMIC4K].
82b0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
82c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
82d0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
82e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
82f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8300: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
8310: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8320: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
8330: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8340: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
8350: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
8360: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8370: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
8380: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
8390: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
83a0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
83b0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
83c0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
83d0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
83e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
83f0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
8400: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
8410: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
8420: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
8430: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
8440: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
8450: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
8460: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
8470: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
8480: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8490: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
84a0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
84b0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
84c0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
84d0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
84e0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
84f0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
8500: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
8510: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
8520: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
8530: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
8540: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8550: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
8560: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8570: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8580: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
8590: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
85a0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
85b0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
85c0: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
85d0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
85e0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
85f0: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
8600: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
8610: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
8620: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
8630: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
8640: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
8650: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8660: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
8670: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
8680: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
8690: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
86a0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
86b0: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
86c0: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
86d0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
86e0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
86f0: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
8700: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
8710: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8720: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
8730: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
8740: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
8750: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8760: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
8770: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
8780: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8790: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
87a0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
87b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
87c0: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
87d0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
87e0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
87f0: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
8800: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8810: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
8820: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
8830: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8840: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
8850: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
8860: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8870: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
8880: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
8890: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
88a0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
88b0: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
88c0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
88d0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
88e0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
88f0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
8900: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
8910: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
8920: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8930: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
8940: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
8950: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
8960: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8970: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8980: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
8990: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
89a0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
89b0: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
89c0: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
89d0: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
89e0: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
89f0: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
8a00: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
8a10: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
8a20: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8a30: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
8a40: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
8a50: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
8a60: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
8a70: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
8a80: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
8a90: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
8aa0: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
8ab0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8ac0: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8ad0: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
8ae0: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
8af0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8b00: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
8b10: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
8b20: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
8b30: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8b40: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8b50: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
8b60: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8b70: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8b80: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
8b90: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
8ba0: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
8bb0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
8bc0: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
8bd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
8be0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
8bf0: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b  rol Opcodes.** K
8c00: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63  EYWORDS: {file c
8c10: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20  ontrol opcodes} 
8c20: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
8c30: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  code}.**.** Thes
8c40: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
8c50: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
8c60: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
8c70: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
8c80: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
8c90: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
8ca0: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
8cb0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8cc0: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
8cd0: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ace..**.** <ul>.
8ce0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8cf0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
8d00: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8d10: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8d20: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8d30: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
8d40: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
8d50: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
8d60: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
8d70: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
8d80: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
8d90: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
8da0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
8db0: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
8dc0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
8dd0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8de0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
8df0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
8e00: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8e10: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
8e20: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
8e30: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
8e40: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
8e50: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
8e60: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
8e70: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f  testing and is o
8e80: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68  nly available wh
8e90: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  en the SQLITE_TE
8ea0: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  ST.** compile-ti
8eb0: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  me option is use
8ec0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
8ed0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
8ee0: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
8ef0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
8f00: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
8f10: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
8f20: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
8f30: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
8f40: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
8f50: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
8f60: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
8f70: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
8f80: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
8f90: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
8fa0: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
8fb0: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
8fc0: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
8fd0: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
8fe0: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
8ff0: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
9000: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
9010: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
9020: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
9030: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
9040: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
9050: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
9060: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
9070: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9080: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9090: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
90a0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
90b0: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
90c0: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
90d0: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
90e0: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
90f0: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
9100: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
9110: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
9120: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
9130: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
9140: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
9150: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9160: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
9170: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
9180: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
9190: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
91a0: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
91b0: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
91c0: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
91d0: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
91e0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
91f0: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
9200: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
9210: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
9220: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
9230: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
9240: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
9250: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
9260: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
9270: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9280: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9290: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
92a0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
92b0: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
92c0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
92d0: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
92e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
92f0: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
9300: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74  ated with a part
9310: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
9320: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
9330: 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  See the [sqlite3
9340: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9350: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
9360: 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
9370: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
9380: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9390: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
93a0: 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67  TED]].** No long
93b0: 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a  er in use..**.**
93c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
93d0: 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68  NTL_SYNC]].** Th
93e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
93f0: 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20  SYNC] opcode is 
9400: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
9410: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61  ally by SQLite a
9420: 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68  nd.** sent to th
9430: 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c  e VFS immediatel
9440: 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79  y before the xSy
9450: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  nc method is inv
9460: 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74  oked on a.** dat
9470: 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72  abase file descr
9480: 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68  iptor. Or, if th
9490: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
94a0: 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a  s not invoked .*
94b0: 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73  * because the us
94c0: 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65  er has configure
94d0: 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a  d SQLite with .*
94e0: 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  * [PRAGMA synchr
94f0: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73  onous | PRAGMA s
9500: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20  ynchronous=OFF] 
9510: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e  it is invoked in
9520: 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68   place .** of th
9530: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20  e xSync method. 
9540: 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74  In most cases, t
9550: 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
9560: 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a  ent passed with.
9570: 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  ** this file-con
9580: 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f  trol is NULL. Ho
9590: 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61  wever, if the da
95a0: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62  tabase file is b
95b0: 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61  eing synced.** a
95c0: 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74  s part of a mult
95d0: 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69  i-database commi
95e0: 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  t, the argument 
95f0: 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d  points to a nul-
9600: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
9610: 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
9620: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  the transactions
9630: 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20   master-journal 
9640: 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73  file name. VFSes
9650: 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74   that .** do not
9660: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9670: 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  l should silentl
9680: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
9690: 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f  code. Applicatio
96a0: 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f  ns .** should no
96b0: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
96c0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
96d0: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65  with this opcode
96e0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
96f0: 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65   .** disrupt the
9700: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
9710: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
9720: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75  Ses that do requ
9730: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20  ire it.  .**.** 
9740: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9750: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
9760: 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  WO]].** The [SQL
9770: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
9780: 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64  _PHASETWO] opcod
9790: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
97a0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
97b0: 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20  ite.** and sent 
97c0: 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72  to the VFS after
97d0: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68   a transaction h
97e0: 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65  as been committe
97f0: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a  d immediately.**
9800: 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20   but before the 
9810: 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f  database is unlo
9820: 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74  cked. VFSes that
9830: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
9840: 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75  s signal.** shou
9850: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9860: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
9870: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
9880: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20  uld not call.** 
9890: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
98a0: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
98b0: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
98c0: 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70  ng so may disrup
98d0: 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74  t the .** operat
98e0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
98f0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
9900: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
9910: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
9920: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9930: 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20  2_AV_RETRY]].** 
9940: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9950: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
9960: 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  Y] opcode is use
9970: 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61  d to configure a
9980: 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72  utomatic.** retr
9990: 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74  y counts and int
99a0: 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61  ervals for certa
99b0: 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72  in disk I/O oper
99c0: 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a  ations for the.*
99d0: 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20  * windows [VFS] 
99e0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76  in order to prov
99f0: 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69  ide robustness i
9a00: 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  n the presence o
9a10: 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20  f.** anti-virus 
9a20: 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65  programs.  By de
9a30: 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f  fault, the windo
9a40: 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72  ws VFS will retr
9a50: 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20  y file read,.** 
9a60: 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20  file write, and 
9a70: 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72  file delete oper
9a80: 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20  ations up to 10 
9a90: 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65  times, with a de
9aa0: 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c  lay.** of 25 mil
9ab0: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65  liseconds before
9ac0: 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79   the first retry
9ad0: 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65   and with the de
9ae0: 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a  lay increasing.*
9af0: 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e  * by an addition
9b00: 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  al 25 millisecon
9b10: 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62  ds with each sub
9b20: 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20  sequent retry.  
9b30: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  This.** opcode a
9b40: 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20  llows these two 
9b50: 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69  values (10 retri
9b60: 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73  es and 25 millis
9b70: 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29  econds of delay)
9b80: 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74  .** to be adjust
9b90: 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20  ed.  The values 
9ba0: 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20  are changed for 
9bb0: 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e  all database con
9bc0: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  nections.** with
9bd0: 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63  in the same proc
9be0: 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ess.  The argume
9bf0: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
9c00: 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74  to an array of t
9c10: 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77  wo.** integers w
9c20: 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69  here the first i
9c30: 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77  nteger i the new
9c40: 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64   retry count and
9c50: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69   the second.** i
9c60: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65  nteger is the de
9c70: 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20  lay.  If either 
9c80: 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74  integer is negat
9c90: 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65  ive, then the se
9ca0: 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20  tting.** is not 
9cb0: 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74  changed but inst
9cc0: 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61  ead the prior va
9cd0: 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74  lue of that sett
9ce0: 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  ing is written.*
9cf0: 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79  * into the array
9d00: 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67   entry, allowing
9d10: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74   the current ret
9d20: 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62  ry settings to b
9d30: 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65  e.** interrogate
9d40: 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20  d.  The zDbName 
9d50: 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e  parameter is ign
9d60: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ored..**.** <li>
9d70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
9d80: 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20  ERSIST_WAL]].** 
9d90: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9da0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20  TL_PERSIST_WAL] 
9db0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9dc0: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
9dd0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
9de0: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68   [WAL | Write Ah
9df0: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67  ead Log] setting
9e00: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
9e10: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20  he auxiliary.** 
9e20: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20  write ahead log 
9e30: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
9e40: 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72  y files used for
9e50: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
9e60: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f  trol.** are auto
9e70: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
9e80: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73  d when the lates
9e90: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  t connection to 
9ea0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
9eb0: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67  closes.  Setting
9ec0: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
9ed0: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73  mode causes thos
9ee0: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69  e files to persi
9ef0: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73  st after.** clos
9f00: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74  e.  Persisting t
9f10: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66  he files is usef
9f20: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72  ul when other pr
9f30: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20  ocesses that do 
9f40: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74  not.** have writ
9f50: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20  e permission on 
9f60: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f  the directory co
9f70: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74  ntaining the dat
9f80: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a  abase file want.
9f90: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64  ** to read the d
9fa0: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73  atabase file, as
9fb0: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61   the WAL and sha
9fc0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9fd0: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69   must exist.** i
9fe0: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20  n order for the 
9ff0: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  database to be r
a000: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f  eadable.  The fo
a010: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a020: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a030: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a040: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a050: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a060: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a070: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a080: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a090: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
a0a0: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
a0b0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  ble persistent.*
a0c0: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20  * WAL mode.  If 
a0d0: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
a0e0: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
a0f0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
a100: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41  he current.** WA
a110: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65  L persistence se
a120: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
a130: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a140: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a150: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a160: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
a170: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a180: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
a190: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
a1a0: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
a1b0: 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65  t "powersafe-ove
a1c0: 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57  rwrite" or "PSOW
a1d0: 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20  " setting.  The 
a1e0: 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20  PSOW setting.** 
a1f0: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b  determines the [
a200: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
a210: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a220: 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20  ] bit of the.** 
a230: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
a240: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20  istics methods. 
a250: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
a260: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
a270: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a280: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
a290: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
a2a0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
a2b0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
a2c0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
a2d0: 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  isable zero-dama
a2e0: 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  ge mode or 1 to 
a2f0: 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  enable zero-dama
a300: 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20  ge.** mode.  If 
a310: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
a320: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
a330: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
a340: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65  he current.** ze
a350: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73  ro-damage mode s
a360: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
a370: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a380: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
a390: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a3a0: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  TL_OVERWRITE] op
a3b0: 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  code is invoked 
a3c0: 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20  by SQLite after 
a3d0: 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69  opening.** a wri
a3e0: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  te transaction t
a3f0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c  o indicate that,
a400: 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f   unless it is ro
a410: 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f  lled back for so
a420: 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68  me.** reason, th
a430: 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73  e entire databas
a440: 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f  e file will be o
a450: 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68  verwritten by th
a460: 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72  e current .** tr
a470: 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20  ansaction. This 
a480: 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55  is used by VACUU
a490: 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  M operations..**
a4a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a4b0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d  _FCNTL_VFSNAME]]
a4c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a4d0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20  _FCNTL_VFSNAME] 
a4e0: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
a4f0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
a500: 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c   names of.** all
a510: 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20   [VFSes] in the 
a520: 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20  VFS stack.  The 
a530: 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c  names are of all
a540: 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74   VFS shims and t
a550: 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74  he.** final bott
a560: 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65  om-level VFS are
a570: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
a580: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
a590: 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
a5a0: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68  malloc()] and th
a5b0: 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72  e result is stor
a5c0: 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20  ed in the char* 
a5d0: 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74  variable.** that
a5e0: 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
a5f0: 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65  meter of [sqlite
a600: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a610: 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20  ] points to..** 
a620: 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65  The caller is re
a630: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72  sponsible for fr
a640: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79  eeing the memory
a650: 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20   when done.  As 
a660: 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65  with.** all file
a670: 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73  -control actions
a680: 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75  , there is no gu
a690: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69  arantee that thi
a6a0: 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a  s will actually.
a6b0: 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20  ** do anything. 
a6c0: 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20   Callers should 
a6d0: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63  initialize the c
a6e0: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f  har* variable to
a6f0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
a700: 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20  er in case this 
a710: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
a720: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e  not implemented.
a730: 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74    This file-cont
a740: 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64  rol.** is intend
a750: 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69  ed for diagnosti
a760: 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  c use only..**.*
a770: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a780: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
a790: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
a7a0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
a7b0: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
a7c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a7d0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
a7e0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
a7f0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
a800: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
a810: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
a820: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
a830: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
a840: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
a850: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
a860: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
a870: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a880: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a890: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
a8a0: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
a8b0: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
a8c0: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
a8d0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
a8e0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
a8f0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
a900: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
a910: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
a920: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
a930: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
a940: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
a950: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
a960: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
a970: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
a980: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a990: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
a9a0: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
a9b0: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
a9c0: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
a9d0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
a9e0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
a9f0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
aa00: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
aa10: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
aa20: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
aa30: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
aa40: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
aa50: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
aa60: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
aa70: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
aa80: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
aa90: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
aaa0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
aab0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
aac0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
aad0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
aae0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
aaf0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
ab00: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
ab10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ab20: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
ab30: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
ab40: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
ab50: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
ab60: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
ab70: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
ab80: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
ab90: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
aba0: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
abb0: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
abc0: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c  atement if resul
abd0: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c  t string is NULL
abe0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e  , or that return
abf0: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
ac00: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  he result string
ac10: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   if the string i
ac20: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e  s non-NULL..** ^
ac30: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
ac40: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ac50: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
ac60: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
ac70: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
ac80: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
ac90: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
aca0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
acb0: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
acc0: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
acd0: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
ace0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
acf0: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
ad00: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
ad10: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
ad20: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
ad30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ad40: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
ad50: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
ad60: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
ad70: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
ad80: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
ad90: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
ada0: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
adb0: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
adc0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
add0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ade0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
adf0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ae00: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
ae10: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
ae20: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
ae30: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
ae40: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
ae50: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
ae60: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
ae70: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
ae80: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
ae90: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
aea0: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
aeb0: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
aec0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
aed0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
aee0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
aef0: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
af00: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
af10: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
af20: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
af30: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
af40: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
af50: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
af60: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
af70: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
af80: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
af90: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
afa0: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
afb0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
afc0: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
afd0: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
afe0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
aff0: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
b000: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
b010: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
b020: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
b030: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
b040: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
b050: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
b060: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
b070: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
b080: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
b090: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b0a0: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
b0b0: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
b0c0: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
b0d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b0e0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
b0f0: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
b100: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
b110: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
b120: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
b130: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
b140: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
b150: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
b160: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b170: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
b180: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
b190: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
b1a0: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
b1b0: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
b1c0: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
b1d0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b1e0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
b1f0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
b200: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
b210: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
b220: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
b230: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
b240: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
b250: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
b260: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
b270: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
b280: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b290: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
b2a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b2b0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
b2c0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b2d0: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
b2e0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
b2f0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
b300: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
b310: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
b320: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
b330: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
b340: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
b350: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
b360: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
b370: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
b380: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b390: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
b3a0: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
b3b0: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
b3c0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
b3d0: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
b3e0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
b3f0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
b400: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
b410: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
b420: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
b430: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
b440: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
b450: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
b460: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
b470: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
b480: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
b490: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
b4a0: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
b4b0: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
b4c0: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
b4d0: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
b4e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
b4f0: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
b500: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b510: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
b520: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
b530: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
b540: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
b550: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
b560: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
b570: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
b580: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
b590: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
b5a0: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
b5b0: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
b5c0: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
b5d0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
b5e0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
b5f0: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
b600: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
b610: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
b620: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
b630: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
b640: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
b650: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
b660: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
b670: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
b680: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
b690: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b6a0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
b6b0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b6c0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
b6d0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
b6e0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
b6f0: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
b700: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
b710: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
b720: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
b730: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
b740: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
b750: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
b760: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
b770: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
b780: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
b790: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
b7a0: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
b7b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b7c0: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
b7d0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
b7e0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
b7f0: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
b800: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
b810: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
b820: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
b830: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
b840: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
b850: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
b860: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
b870: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
b880: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
b890: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
b8a0: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
b8b0: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
b8c0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
b8d0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
b8e0: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
b8f0: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  efined..**.** <l
b900: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b910: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20  _WAL_BLOCK]].** 
b920: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b930: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20  L_WAL_BLOCK] is 
b940: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
b950: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69  VFS layer that i
b960: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64  t might.** be ad
b970: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c  vantageous to bl
b980: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  ock on the next 
b990: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20  WAL lock if the 
b9a0: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65  lock is not imme
b9b0: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c  diately.** avail
b9c0: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73  able.  The WAL s
b9d0: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20  ubsystem issues 
b9e0: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69  this signal duri
b9f0: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75  ng rare.** circu
ba00: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65  mstances in orde
ba10: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c  r to fix a probl
ba20: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79  em with priority
ba30: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41   inversion..** A
ba40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
ba50: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  ld <em>not</em> 
ba60: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  use this file-co
ba70: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ntrol..**.** <li
ba80: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
ba90: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20  ZIPVFS]].** The 
baa0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
bab0: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20  PVFS] opcode is 
bac0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a  implemented by z
bad0: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20  ipvfs only. All 
bae0: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f  other.** VFS sho
baf0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
bb00: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74  E_NOTFOUND for t
bb10: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a  his opcode..**.*
bb20: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bb30: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68  CNTL_RBU]].** Th
bb40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bb50: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  RBU] opcode is i
bb60: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
bb70: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73  e special VFS us
bb80: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55  ed by.** the RBU
bb90: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e   extension only.
bba0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20    All other VFS 
bbb0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
bbc0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
bbd0: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65  r.** this opcode
bbe0: 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .  .** </ul>.*/.
bbf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bc00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
bc10: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
bc20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bc30: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
bc40: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
bc50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bc60: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
bc70: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
bc80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bc90: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
bca0: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
bcb0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bcc0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
bcd0: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
bce0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bcf0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
bd00: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
bd10: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
bd20: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
bd30: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
bd40: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
bd50: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
bd60: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
bd70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bd80: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
bd90: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
bda0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
bdb0: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
bdc0: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
bdd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
bde0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
bdf0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
be00: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
be10: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
be20: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
be30: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
be40: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
be50: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
be60: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
be70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
be80: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
be90: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
bea0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
beb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bec0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
bed0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
bee0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bef0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
bf00: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
bf10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bf20: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
bf30: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
bf40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bf50: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
bf60: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
bf70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bf80: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
bf90: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
bfa0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bfb0: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
bfc0: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69          22.#defi
bfd0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bfe0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
bff0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e         23.#defin
c000: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
c010: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20  AL_BLOCK        
c020: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65        24.#define
c030: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49   SQLITE_FCNTL_ZI
c040: 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20  PVFS            
c050: 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20       25.#define 
c060: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
c070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c080: 20 20 20 20 32 36 0a 0a 2f 2a 20 64 65 70 72 65      26../* depre
c090: 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23  cated names */.#
c0a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45  define SQLITE_GE
c0b0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
c0c0: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
c0d0: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_GET_LOCKPROXYF
c0e0: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
c0f0: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
c100: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
c110: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
c120: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
c130: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
c140: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53  NO             S
c150: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
c160: 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  _ERRNO.../*.** C
c170: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
c180: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  andle.**.** The 
c190: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
c1a0: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
c1b0: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
c1c0: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
c1d0: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
c1e0: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
c1f0: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
c200: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
c210: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
c220: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
c230: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
c240: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
c250: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
c260: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
c270: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
c280: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
c290: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
c2a0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
c2b0: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
c2c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
c2d0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
c2e0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
c2f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
c300: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
c310: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
c320: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
c330: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
c340: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
c350: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
c360: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
c370: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
c380: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
c390: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
c3a0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
c3b0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
c3c0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
c3d0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20   file system".  
c3e0: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20  See.** the [VFS 
c3f0: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74  | VFS documentat
c400: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72  ion] for further
c410: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
c420: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
c430: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
c440: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
c450: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
c460: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
c470: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
c480: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
c490: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
c4a0: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
c4b0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
c4c0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
c4d0: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
c4e0: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
c4f0: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
c500: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
c510: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
c520: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
c530: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
c540: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
c550: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
c560: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
c570: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
c580: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
c590: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
c5a0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
c5b0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
c5c0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
c5d0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
c5e0: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
c5f0: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
c600: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
c610: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
c620: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
c630: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
c640: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
c650: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
c660: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
c670: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
c680: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
c690: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
c6a0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
c6b0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
c6c0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
c6d0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
c6e0: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
c6f0: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
c700: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
c710: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
c720: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
c730: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
c740: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
c750: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
c760: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
c770: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
c780: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
c790: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
c7a0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
c7b0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
c7c0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
c7d0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
c7e0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
c7f0: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
c800: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
c810: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
c820: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
c830: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
c840: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
c850: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
c860: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
c870: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
c880: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
c890: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
c8a0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
c8b0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
c8c0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
c8d0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
c8e0: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
c8f0: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
c900: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
c910: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
c920: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
c930: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
c940: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
c950: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
c960: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
c970: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
c980: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
c990: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
c9a0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
c9b0: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
c9c0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
c9d0: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
c9e0: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
c9f0: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
ca00: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
ca10: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
ca20: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
ca30: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
ca40: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
ca50: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
ca60: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
ca70: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
ca80: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
ca90: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
caa0: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
cab0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
cac0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
cad0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
cae0: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
caf0: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
cb00: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
cb10: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
cb20: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
cb30: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
cb40: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
cb50: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
cb60: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
cb70: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
cb80: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
cb90: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
cba0: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
cbb0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
cbc0: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
cbd0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
cbe0: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
cbf0: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
cc00: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
cc10: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
cc20: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
cc30: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
cc40: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
cc50: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
cc60: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
cc70: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
cc80: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
cc90: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
cca0: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
ccb0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
ccc0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
ccd0: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
cce0: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
ccf0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
cd00: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
cd10: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
cd20: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
cd30: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
cd40: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
cd50: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
cd60: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
cd70: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
cd80: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
cd90: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
cda0: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
cdb0: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
cdc0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
cdd0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
cde0: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
cdf0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
ce00: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
ce10: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
ce20: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
ce30: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
ce40: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
ce50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
ce60: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
ce70: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
ce80: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
ce90: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
cea0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
ceb0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
cec0: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
ced0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
cee0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
cef0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
cf00: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
cf10: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cf20: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
cf30: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
cf40: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
cf50: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
cf60: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
cf70: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
cf80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
cf90: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
cfa0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cfb0: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
cfc0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
cfd0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
cfe0: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
cff0: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
d000: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
d010: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
d020: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
d030: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
d040: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
d050: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
d060: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
d070: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
d080: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
d090: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
d0a0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
d0b0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
d0c0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
d0d0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
d0e0: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
d0f0: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
d100: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
d110: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
d120: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
d130: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
d140: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
d150: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
d160: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
d170: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
d180: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
d190: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
d1a0: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
d1b0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
d1c0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
d1d0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
d1e0: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
d1f0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
d200: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
d210: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
d220: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
d230: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
d240: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d250: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
d260: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
d270: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
d280: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
d290: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
d2a0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
d2b0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
d2c0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
d2d0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
d2e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
d2f0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
d300: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
d310: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
d320: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
d330: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
d340: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
d350: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
d360: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
d370: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
d380: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
d390: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
d3a0: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
d3b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
d3c0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
d3d0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
d3e0: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
d3f0: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
d400: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
d410: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
d420: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
d430: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
d440: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
d450: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
d460: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
d470: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
d480: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
d490: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
d4a0: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
d4b0: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
d4c0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
d4d0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
d4e0: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
d4f0: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
d500: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
d510: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
d520: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
d530: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
d540: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
d550: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
d560: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
d570: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
d580: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
d590: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
d5a0: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
d5b0: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
d5c0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
d5d0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
d5e0: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
d5f0: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
d600: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
d610: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
d620: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
d630: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
d640: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
d650: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
d660: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
d670: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
d680: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
d690: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
d6a0: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
d6b0: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
d6c0: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
d6d0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
d6e0: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
d6f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
d700: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
d710: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
d720: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
d730: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
d740: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
d750: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
d760: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
d770: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
d780: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
d790: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
d7a0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
d7b0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
d7c0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
d7d0: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
d7e0: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
d7f0: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
d800: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
d810: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
d820: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
d830: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
d840: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
d850: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
d860: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
d870: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
d880: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
d890: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
d8a0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
d8b0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
d8c0: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
d8d0: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
d8e0: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
d8f0: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
d900: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
d910: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
d920: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
d930: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
d940: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
d950: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
d960: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
d970: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
d980: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
d990: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
d9a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
d9b0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
d9c0: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
d9d0: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
d9e0: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
d9f0: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
da00: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
da10: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
da20: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
da30: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
da40: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
da50: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
da60: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
da70: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
da80: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
da90: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
daa0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
dab0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
dac0: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
dad0: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
dae0: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
daf0: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
db00: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
db10: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
db20: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
db30: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
db40: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
db50: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
db60: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
db70: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
db80: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
db90: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
dba0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
dbb0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
dbc0: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
dbd0: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
dbe0: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
dbf0: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
dc00: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
dc10: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
dc20: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
dc30: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
dc40: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
dc50: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
dc60: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
dc70: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
dc80: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
dc90: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
dca0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
dcb0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
dcc0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
dcd0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
dce0: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
dcf0: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
dd00: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
dd10: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
dd20: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
dd30: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
dd40: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
dd50: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
dd60: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
dd70: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
dd80: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
dd90: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
dda0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
ddb0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
ddc0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
ddd0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
dde0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
ddf0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
de00: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
de10: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
de20: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
de30: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
de40: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
de50: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
de60: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
de70: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
de80: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
de90: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
dea0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
deb0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
dec0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
ded0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
dee0: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
def0: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
df00: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
df10: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
df20: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
df30: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
df40: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
df50: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
df60: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
df70: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
df80: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
df90: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
dfa0: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
dfb0: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
dfc0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
dfd0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
dfe0: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
dff0: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
e000: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
e010: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
e020: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
e030: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
e040: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
e050: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
e060: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
e070: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
e080: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
e090: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
e0a0: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
e0b0: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
e0c0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
e0d0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
e0e0: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
e0f0: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
e100: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
e110: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
e120: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
e130: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
e140: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
e150: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
e160: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
e170: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
e180: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
e190: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
e1a0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
e1b0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
e1c0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
e1d0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
e1e0: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
e1f0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
e200: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
e210: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
e220: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
e230: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
e240: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
e250: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
e260: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
e270: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
e280: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
e290: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
e2a0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
e2b0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
e2c0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
e2d0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
e2e0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
e2f0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
e300: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
e310: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
e320: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
e330: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
e340: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
e350: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
e360: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
e370: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
e380: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
e390: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e3a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
e3b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
e3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
e3d0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
e3e0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
e3f0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(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 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
e430: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
e440: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e450: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
e460: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
e470: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
e480: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
e490: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e4a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
e4b0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
e4c0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
e4d0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
e4e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e4f0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
e500: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
e510: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e520: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
e530: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
e540: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
e550: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
e560: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
e570: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
e580: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
e590: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e5a0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
e5b0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
e5c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
e5d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
e5e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
e5f0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
e600: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
e610: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
e620: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
e630: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
e640: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
e650: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
e660: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
e670: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
e680: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e690: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
e6a0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
e6b0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
e6c0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
e6d0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
e6e0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
e6f0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
e700: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
e710: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
e720: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
e730: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
e740: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e750: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e760: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
e770: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
e780: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
e790: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
e7a0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
e7b0: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
e7c0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
e7d0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
e7e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e7f0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
e800: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
e810: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
e820: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
e830: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e840: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e850: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
e860: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
e870: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
e880: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e890: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
e8a0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
e8b0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
e8c0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
e8d0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
e8e0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
e8f0: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
e900: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
e910: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
e920: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
e930: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
e940: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
e950: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
e960: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
e970: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
e980: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
e990: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
e9a0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
e9b0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
e9c0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
e9d0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
e9e0: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
e9f0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
ea00: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
ea10: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
ea20: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
ea30: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
ea40: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ea50: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
ea60: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
ea70: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
ea80: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ea90: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
eaa0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
eab0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
eac0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
ead0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
eae0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
eaf0: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
eb00: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
eb10: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
eb20: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
eb30: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
eb40: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
eb50: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
eb60: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
eb70: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
eb80: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
eb90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
eba0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
ebb0: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
ebc0: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
ebd0: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
ebe0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
ebf0: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
ec00: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
ec10: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
ec20: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
ec30: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
ec40: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
ec50: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
ec60: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
ec70: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
ec80: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
ec90: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
eca0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
ecb0: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
ecc0: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
ecd0: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
ece0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
ecf0: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
ed00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
ed10: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
ed20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ed30: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
ed40: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
ed50: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
ed60: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
ed70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
ed80: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
ed90: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
eda0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
edb0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
edc0: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
edd0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
ede0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
edf0: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
ee00: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
ee10: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
ee20: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
ee30: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
ee40: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
ee50: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
ee60: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
ee70: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
ee80: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
ee90: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
eea0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
eeb0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
eec0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
eed0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
eee0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
eef0: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
ef00: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
ef10: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
ef20: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
ef30: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
ef40: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
ef50: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
ef60: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
ef70: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
ef80: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
ef90: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
efa0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
efb0: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
efc0: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
efd0: 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
efe0: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
eff0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
f000: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
f010: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
f020: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
f030: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
f040: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
f050: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
f060: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
f070: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
f080: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
f090: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
f0a0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
f0b0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
f0c0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
f0d0: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
f0e0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
f0f0: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
f100: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
f110: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
f120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
f130: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
f140: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
f150: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
f160: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
f170: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
f180: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
f190: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
f1a0: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
f1b0: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
f1c0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
f1d0: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
f1e0: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
f1f0: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
f200: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
f210: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
f220: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f230: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
f240: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
f250: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
f260: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
f270: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
f280: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f290: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
f2a0: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
f2b0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
f2c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
f2d0: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
f2e0: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
f2f0: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
f300: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
f310: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
f320: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
f330: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
f340: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
f350: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
f360: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
f370: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
f380: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
f390: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
f3a0: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
f3b0: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
f3c0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
f3d0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
f3e0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
f3f0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
f400: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f410: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
f420: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
f430: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
f440: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
f450: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
f460: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
f470: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
f480: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
f490: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
f4a0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
f4b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f4c0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
f4d0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
f4e0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f4f0: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
f500: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
f510: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
f520: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
f530: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
f540: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
f550: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
f560: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
f570: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
f580: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f590: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
f5a0: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
f5b0: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
f5c0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
f5d0: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
f5e0: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
f5f0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
f600: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
f610: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
f620: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f630: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
f640: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
f650: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
f660: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
f670: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
f680: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
f690: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
f6a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f6b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
f6c0: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
f6d0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f6e0: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
f6f0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f700: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
f710: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
f720: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
f730: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
f740: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
f750: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
f760: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
f770: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
f780: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
f790: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
f7a0: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
f7b0: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
f7c0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
f7d0: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
f7e0: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
f7f0: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
f800: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
f810: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
f820: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
f830: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
f840: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
f850: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
f860: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f870: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f880: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
f890: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
f8a0: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
f8b0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
f8c0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f8d0: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
f8e0: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
f8f0: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
f900: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
f910: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
f920: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
f930: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
f940: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
f950: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
f960: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
f970: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
f980: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f990: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
f9a0: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
f9b0: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
f9c0: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
f9d0: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
f9e0: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
f9f0: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
fa00: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
fa10: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fa20: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
fa30: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
fa40: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
fa50: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
fa60: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
fa70: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
fa80: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
fa90: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
faa0: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
fab0: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
fac0: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
fad0: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
fae0: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
faf0: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
fb00: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
fb10: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
fb20: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
fb30: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
fb40: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
fb50: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
fb60: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
fb70: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
fb80: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
fb90: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
fba0: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
fbb0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
fbc0: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
fbd0: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
fbe0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
fbf0: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
fc00: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
fc10: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
fc20: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
fc30: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
fc40: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fc50: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
fc60: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
fc70: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
fc80: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
fc90: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
fca0: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
fcb0: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
fcc0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
fcd0: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
fce0: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
fcf0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
fd00: 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
fd10: 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
fd20: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
fd30: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
fd40: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
fd50: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
fd60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
fd70: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
fd80: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
fd90: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
fda0: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
fdb0: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
fdc0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
fdd0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
fde0: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
fdf0: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
fe00: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
fe10: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
fe20: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
fe30: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
fe40: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
fe50: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
fe60: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
fe70: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
fe80: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
fe90: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
fea0: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
feb0: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
fec0: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
fed0: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
fee0: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
fef0: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
ff00: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
ff10: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
ff20: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
ff30: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
ff40: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
ff50: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
ff60: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
ff70: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
ff80: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
ff90: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
ffa0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ffb0: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
ffc0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
ffd0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
ffe0: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
fff0: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
10000 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
10010 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10020 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
10030 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
10040 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
10050 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
10060 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
10070 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
10080 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
10090 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
100a0 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
100b0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
100c0 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
100d0 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
100e0 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
100f0 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
10100 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
10110 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
10120 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
10130 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
10140 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
10150 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
10160 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
10170 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
10180 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
10190 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
101a0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
101b0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
101c0 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
101d0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
101e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
101f0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10200 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
10210 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
10220 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
10230 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
10240 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
10250 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
10260 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54  ailure..*/.SQLIT
10270 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
10280 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
10290 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
102a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
102b0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
102c0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
102d0 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  n(void);.SQLITE_
102e0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
102f0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f  TDCALL sqlite3_o
10300 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51  s_init(void);.SQ
10310 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
10320 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
10330 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
10340 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10350 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
10360 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
10370 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
10380 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
10390 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
103a0 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
103b0 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
103c0 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
103d0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
103e0 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
103f0 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
10400 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
10410 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
10420 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
10430 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
10440 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
10450 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
10460 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
10470 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
10480 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
10490 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
104a0 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
104b0 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
104c0 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
104d0 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f   <b>The sqlite3_
104e0 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
104f0 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
10500 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63  safe. The applic
10510 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e  ation.** must en
10520 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
10530 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
10540 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
10550 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
10560 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
10570 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
10580 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a  unning.</b>.**.*
10590 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
105a0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
105b0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
105c0 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
105d0 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
105e0 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
105f0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
10600 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
10610 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
10620 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10630 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
10640 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
10650 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
10660 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10670 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
10680 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
10690 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
106a0 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
106b0 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
106c0 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
106d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
106e0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
106f0 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
10700 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
10710 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
10720 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
10730 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
10740 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
10750 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
10760 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
10770 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
10780 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10790 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
107a0 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
107b0 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
107c0 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
107d0 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
107e0 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
107f0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
10800 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
10810 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
10820 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
10830 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
10840 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
10850 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
10860 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10870 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
10880 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
10890 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
108a0 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
108b0 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
108c0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
108d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
108e0 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
108f0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
10900 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
10910 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c  SQLITE_CDECL sql
10920 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
10930 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
10940 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
10950 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
10960 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
10970 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
10980 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
10990 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
109a0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
109b0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
109c0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
109d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
109e0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
109f0 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
10a00 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
10a10 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
10a20 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
10a30 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
10a40 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
10a50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
10a60 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
10a70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
10a80 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
10a90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
10aa0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
10ab0 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
10ac0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
10ad0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
10ae0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
10af0 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
10b00 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
10b10 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
10b20 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
10b30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10b40 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
10b50 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
10b60 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
10b70 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
10b80 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
10b90 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
10ba0 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
10bb0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
10bc0 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
10bd0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
10be0 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
10bf0 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
10c00 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
10c10 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43   int SQLITE_CDEC
10c20 4c 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  L sqlite3_db_con
10c30 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  fig(sqlite3*, in
10c40 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  t op, ...);../*.
10c50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
10c60 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
10c70 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e  outines.**.** An
10c80 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
10c90 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
10ca0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
10cb0 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
10cc0 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
10cd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10ce0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
10cf0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
10d00 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
10d10 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
10d20 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
10d30 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
10d40 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
10d50 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
10d60 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
10d70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10d80 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
10d90 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10da0 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
10db0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f  CONFIG_MALLOC] o
10dc0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
10dd0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a  _GETMALLOC].  .*
10de0 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e  * By creating an
10df0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
10e00 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
10e10 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
10e20 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
10e30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
10e40 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67  LLOC]).** during
10e50 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
10e60 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  an application c
10e70 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
10e80 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
10e90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
10ea0 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c  ubsystem for SQL
10eb0 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
10ec0 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e  ll of its.** dyn
10ed0 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
10ee0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
10ef0 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
10f00 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75  with several [bu
10f10 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
10f20 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61  locators].** tha
10f30 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20  t are perfectly 
10f40 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
10f50 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
10f60 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
10f70 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
10f80 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
10f90 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
10fa0 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
10fb0 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
10fc0 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
10fd0 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
10fe0 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
10ff0 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
11000 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
11010 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
11020 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
11030 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
11040 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
11050 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11060 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
11070 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
11080 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
11090 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
110a0 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
110b0 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
110c0 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
110d0 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
110e0 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
110f0 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64  c, xRealloc, and
11100 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
11110 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
11120 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72  e.** malloc(), r
11130 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  ealloc() and fre
11140 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  e() functions fr
11150 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
11160 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53  C library..** ^S
11170 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
11180 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
11190 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
111a0 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61  xRealloc is alwa
111b0 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72  ys a value retur
111c0 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63  ned by a prior c
111d0 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e  all to xRoundup.
111e0 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
111f0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
11200 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
11210 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
11220 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
11230 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
11240 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
11250 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
11260 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
11270 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
11280 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
11290 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
112a0 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
112b0 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
112c0 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
112d0 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
112e0 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
112f0 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
11300 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
11310 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
11320 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
11330 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
11340 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
11350 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
11360 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
11370 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
11380 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
11390 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
113a0 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
113b0 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
113c0 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
113d0 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79  .** Every memory
113e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
113f0 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68  est coming in th
11400 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d  rough [sqlite3_m
11410 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b  alloc()].** or [
11420 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
11430 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78  )] first calls x
11440 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f  Roundup.  If xRo
11450 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c  undup returns 0,
11460 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73   .** that causes
11470 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
11480 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ng memory alloca
11490 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a  tion to fail..**
114a0 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
114b0 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
114c0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
114d0 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d  cator.  For exam
114e0 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
114f0 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
11500 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
11510 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
11520 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
11530 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
11540 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
11550 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
11560 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
11570 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11580 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
11590 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
115a0 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
115b0 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
115c0 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
115d0 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
115e0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
115f0 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
11600 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
11610 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
11620 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
11630 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
11640 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
11650 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
11660 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
11670 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
11680 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
11690 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
116a0 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
116b0 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
116c0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
116d0 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
116e0 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
116f0 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
11700 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
11710 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
11720 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
11730 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
11740 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
11750 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
11760 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
11770 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
11780 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11790 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
117a0 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
117b0 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
117c0 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
117d0 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
117e0 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
117f0 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
11800 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
11810 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
11820 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
11830 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
11840 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
11850 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
11860 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
11870 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
11880 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
11890 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
118a0 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
118b0 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
118c0 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
118d0 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
118e0 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
118f0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
11900 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
11910 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
11920 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
11930 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
11940 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
11950 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
11960 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
11970 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
11980 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
11990 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
119a0 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
119b0 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
119c0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
119d0 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
119e0 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
119f0 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
11a00 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
11a10 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
11a20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
11a30 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
11a40 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
11a50 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
11a60 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
11a70 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
11a80 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
11a90 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
11aa0 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
11ab0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
11ac0 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
11ad0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11ae0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
11af0 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
11b00 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
11b10 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
11b20 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
11b30 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
11b40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
11b50 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
11b60 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
11b70 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
11b80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
11b90 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
11ba0 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
11bb0 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  {configuration o
11bc0 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ption}.**.** The
11bd0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
11be0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
11bf0 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
11c00 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
11c10 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
11c20 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
11c30 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
11c40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11c50 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
11c60 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
11c70 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
11c80 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
11c90 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
11ca0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
11cb0 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
11cc0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
11cd0 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
11ce0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
11cf0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
11d00 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
11d10 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
11d20 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
11d30 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
11d40 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
11d50 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
11d60 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
11d70 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
11d80 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
11d90 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
11da0 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
11db0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
11dc0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
11dd0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
11de0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
11df0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11e00 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
11e10 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
11e20 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
11e30 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
11e40 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
11e50 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
11e60 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
11e70 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
11e80 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
11e90 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
11ea0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
11eb0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
11ec0 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
11ed0 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
11ee0 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
11ef0 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
11f00 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
11f10 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
11f20 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
11f30 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
11f40 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
11f50 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
11f60 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
11f70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
11f80 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
11f90 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74  to change the [t
11fa0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66  hreading mode] f
11fb0 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a  rom its default.
11fc0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67  ** value of Sing
11fd0 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f  le-thread and so
11fe0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11ff0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
12000 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
12010 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
12020 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
12030 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
12040 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
12050 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
12060 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12070 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
12080 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12090 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
120a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
120b0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
120c0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
120d0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
120e0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
120f0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
12100 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
12110 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12120 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
12130 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
12140 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12150 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12160 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
12170 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
12180 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
12190 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
121a0 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
121b0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
121c0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
121d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
121e0 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
121f0 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
12200 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
12210 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
12220 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
12230 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
12240 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
12250 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
12260 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
12270 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
12280 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
12290 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
122a0 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
122b0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
122c0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
122d0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
122e0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
122f0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
12300 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
12310 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
12320 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
12330 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
12340 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12350 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
12360 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
12370 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
12380 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
12390 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
123a0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
123b0 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
123c0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
123d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
123e0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
123f0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12400 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
12410 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
12420 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
12430 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
12440 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
12450 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
12460 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
12470 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20   Serialized. In 
12480 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69  other words, thi
12490 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
124a0 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
124b0 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
124c0 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
124d0 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
124e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
124f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
12500 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
12510 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
12520 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
12530 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
12540 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12550 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
12560 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
12570 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
12580 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
12590 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
125a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
125b0 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
125c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
125d0 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
125e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
125f0 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
12600 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
12610 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
12620 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
12630 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
12640 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
12650 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
12660 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  time..** ^If SQL
12670 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12680 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
12690 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
126a0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
126b0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
126c0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
126d0 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
126e0 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
126f0 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  Serialized [thre
12700 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
12710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
12720 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
12730 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
12740 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
12750 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
12760 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
12770 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12780 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
12790 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
127a0 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
127b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
127c0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
127d0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
127e0 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  FIG_MALLOC optio
127f0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
12800 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
12810 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
12820 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
12830 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12840 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
12850 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
12860 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
12870 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
12880 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
12890 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
128a0 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
128b0 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   in place of.** 
128c0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
128d0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62  ation routines b
128e0 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
128f0 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  .)^ ^SQLite make
12900 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69  s.** its own pri
12910 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
12920 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
12930 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
12940 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a  hods] structure.
12950 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73  ** before the [s
12960 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12970 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f   call returns.</
12980 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12990 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
129a0 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
129b0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
129c0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
129d0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
129e0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74  IG_GETMALLOC opt
129f0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12a00 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
12a10 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
12a20 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
12a30 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12a40 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12a50 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
12a60 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
12a70 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
12a80 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
12a90 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
12aa0 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
12ab0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
12ac0 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
12ad0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
12ae0 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
12af0 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
12b00 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
12b10 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
12b20 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
12b30 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
12b40 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
12b50 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
12b60 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
12b70 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a  example. </dd>.*
12b80 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12b90 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d  NFIG_MEMSTATUS]]
12ba0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12bb0 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
12bc0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
12bd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12be0 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61  STATUS option ta
12bf0 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  kes single argum
12c00 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c  ent of type int,
12c10 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20  .** interpreted 
12c20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68  as a boolean, wh
12c30 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
12c40 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
12c50 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d  ection of.** mem
12c60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
12c70 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
12c80 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
12c90 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
12ca0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20  re.** disabled, 
12cb0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
12cc0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
12cd0 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
12ce0 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
12cf0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
12d00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
12d10 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
12d20 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
12d30 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
12d40 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
12d50 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
12d60 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
12d70 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29  lite3_status64()
12d80 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
12d90 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
12da0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
12db0 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
12dc0 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
12dd0 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
12de0 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
12df0 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
12e00 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
12e10 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
12e20 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
12e30 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
12e40 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
12e50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
12e70 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TCH]] <dt>SQLITE
12e80 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c  _CONFIG_SCRATCH<
12e90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
12ea0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12eb0 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73  SCRATCH option s
12ec0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
12ed0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a  c memory buffer.
12ee0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  ** that SQLite c
12ef0 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74  an use for scrat
12f00 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68  ch memory.  ^(Th
12f10 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
12f20 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51  guments.** to SQ
12f30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
12f40 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  TCH:  A pointer 
12f50 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
12f60 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
12f70 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
12f80 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
12f90 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
12fa0 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
12fb0 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
12fc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
12fd0 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
12fe0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
12ff0 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
13000 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65  ns (N).)^.** The
13010 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13020 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
13030 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
13040 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
13050 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
13060 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
13070 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
13080 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20  ll not use more 
13090 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68  than one scratch
130a0 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72   buffers per thr
130b0 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ead..** ^SQLite 
130c0 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65  will never reque
130d0 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66  st a scratch buf
130e0 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
130f0 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73   than 6.** times
13100 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
13110 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  ge size..** ^If 
13120 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
13130 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
13140 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
13150 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
13160 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
13170 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13180 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
13190 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
131a0 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
131b0 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
131c0 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a  ory needed.<p>.*
131d0 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c  * ^When the appl
131e0 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73  ication provides
131f0 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73   any amount of s
13200 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73  cratch memory us
13210 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  ing.** SQLITE_CO
13220 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51  NFIG_SCRATCH, SQ
13230 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65  Lite avoids unne
13240 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a  cessary large.**
13250 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13260 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e  |heap allocation
13270 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20  s]..** This can 
13280 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f  help [Robson pro
13290 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72  of|prevent memor
132a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
132b0 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65  lures] due to he
132c0 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74  ap.** fragmentat
132d0 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72  ion in low-memor
132e0 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  y embedded syste
132f0 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ms..** </dd>.**.
13300 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13310 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c  IG_PAGECACHE]] <
13320 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13330 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
13340 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
13350 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
13360 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63  ACHE option spec
13370 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
13380 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20  emory buffer.** 
13390 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
133a0 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61  use for the data
133b0 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
133c0 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
133d0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
133e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
133f0 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
13400 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f  ration should no
13410 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20  t be used if an 
13420 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
13430 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  ne page.** cache
13440 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
13450 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20  is loaded using 
13460 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
13470 49 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20 63  IG_PCACHE2].** c
13480 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13490 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61  ion..** ^There a
134a0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
134b0 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ts to SQLITE_CON
134c0 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41  FIG_PAGECACHE: A
134d0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38   pointer to.** 8
134e0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
134f0 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
13500 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
13510 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
13520 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
13530 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
13540 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
13550 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
13560 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
13570 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
13580 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
13590 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36  etween 512 and 6
135a0 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20  5536) plus some 
135b0 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20  extra bytes for 
135c0 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
135d0 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65  der.  ^The numbe
135e0 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73  r of extra bytes
135f0 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70   needed by the p
13600 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61  age header.** ca
13610 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
13620 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
13630 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
13640 48 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a 2a  HDRSZ] option .*
13650 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  * to [sqlite3_co
13660 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74 20  nfig()]..** ^It 
13670 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
13680 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
13690 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f  ed memory,.** fo
136a0 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74  r the sz paramet
136b0 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20  er to be larger 
136c0 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20  than necessary. 
136d0 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
136e0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
136f0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
13700 74 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b  te aligned block
13710 20 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74 0a   of memory that.
13720 2a 2a 20 69 73 20 61 74 20 6c 65 61 73 74 20 73  ** is at least s
13730 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
13740 6f 72 79 2c 20 6f 74 68 65 72 77 69 73 65 20 73  ory, otherwise s
13750 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
13760 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
13770 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ed..** ^SQLite w
13780 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f  ill use the memo
13790 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  ry provided by t
137a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
137b0 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73  t to satisfy its
137c0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  .** memory needs
137d0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e   for the first N
137e0 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61   pages that it a
137f0 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e  dds to cache.  ^
13800 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
13810 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
13820 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
13830 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
13840 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
13850 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
13860 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
13870 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
13880 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
13890 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
138a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
138b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
138c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
138d0 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
138e0 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
138f0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
13900 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
13910 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
13920 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20  buffer .** that 
13930 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
13940 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
13950 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
13960 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a  location needs.*
13970 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  * beyond those p
13980 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b  rovided for by [
13990 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
139a0 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53  RATCH] and.** [S
139b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
139c0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65  ECACHE]..** ^The
139d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
139e0 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  EAP option is on
139f0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
13a00 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13a10 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65  ed.** with eithe
13a20 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
13a30 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51  _MEMSYS3] or [SQ
13a40 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
13a50 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73  YS5] and returns
13a60 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
13a70 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74  R] if invoked ot
13a80 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65  herwise..** ^The
13a90 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
13aa0 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
13ab0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a  _CONFIG_HEAP:.**
13ac0 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   An 8-byte align
13ad0 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ed pointer to th
13ae0 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65  e memory,.** the
13af0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
13b00 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
13b10 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
13b20 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
13b30 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74  n size..** ^If t
13b40 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
13b50 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
13b60 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
13b70 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
13b80 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
13b90 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
13ba0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
13bb0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
13bc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
13bd0 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
13be0 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
13bf0 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
13c00 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49  FIG_MALLOC].  ^I
13c10 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
13c20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
13c30 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ULL then the alt
13c40 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
13c50 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
13c60 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
13c70 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
13c80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13c90 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
13ca0 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
13cb0 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
13cc0 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
13cd0 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
13ce0 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
13cf0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
13d00 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
13d10 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
13d20 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20  .** The minimum 
13d30 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
13d40 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a  is capped at 2**
13d50 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76  12. Reasonable v
13d60 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65  alues.** for the
13d70 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
13d80 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a  ion size are 2**
13d90 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c  5 through 2**8.<
13da0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13db0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
13dc0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13dd0 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
13de0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
13df0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
13e00 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
13e10 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13e20 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70   which is a.** p
13e30 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
13e40 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
13e50 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
13e60 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
13e70 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
13e80 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e  specifies altern
13e90 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
13ea0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
13eb0 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20  o be used.** in 
13ec0 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20  place the mutex 
13ed0 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
13ee0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
13ef0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
13f00 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
13f10 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
13f20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
13f30 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
13f40 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
13f50 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
13f60 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
13f70 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
13f80 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
13f90 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
13fa0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
13fb0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
13fc0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
13fd0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
13fe0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
13ff0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
14000 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
14010 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
14020 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
14030 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
14040 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
14050 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
14060 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
14070 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
14080 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
14090 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
140a0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
140b0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
140c0 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
140d0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
140e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
140f0 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  TMUTEX option ta
14100 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14110 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
14120 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
14130 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
14140 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
14150 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
14160 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
14170 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
14180 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
14190 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
141a0 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
141b0 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
141c0 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
141d0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
141e0 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
141f0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
14200 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
14210 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
14220 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
14230 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
14240 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
14250 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
14260 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
14270 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
14280 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
14290 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
142a0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
142b0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
142c0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
142d0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
142e0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
142f0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
14300 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
14310 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
14320 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
14330 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
14340 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
14350 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14360 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
14370 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
14380 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
14390 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
143a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
143b0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c  IG_LOOKASIDE]] <
143c0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
143d0 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
143e0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
143f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14400 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b  ASIDE option tak
14410 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
14420 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a   that determine.
14430 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73  ** the default s
14440 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65  ize of lookaside
14450 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20   memory on each 
14460 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14470 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69  tion]..** The fi
14480 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
14490 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
144a0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
144b0 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
144c0 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
144d0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
144e0 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
144f0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
14500 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53  nnection.)^  ^(S
14510 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14520 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74  KASIDE.** sets t
14530 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  he <i>default</i
14540 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
14550 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
14560 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14570 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b  ].** option to [
14580 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
14590 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
145a0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
145b0 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
145c0 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
145d0 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
145e0 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
145f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14600 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  IG_PCACHE2]] <dt
14610 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
14620 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
14630 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
14640 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
14650 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14660 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14670 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f  hich is .** a po
14680 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
14690 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
146a0 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54  ods2] object.  T
146b0 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
146c0 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65  fies.** the inte
146d0 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f  rface to a custo
146e0 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
146f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a  lementation.)^.*
14700 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  * ^SQLite makes 
14710 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
14720 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
14730 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c  thods2] object.<
14740 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14750 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14760 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
14770 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14780 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
14790 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
147a0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
147b0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
147c0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
147d0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
147e0 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
147f0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
14800 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
14810 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a  QLite copies of.
14820 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70  ** the current p
14830 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
14840 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
14850 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
14860 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14870 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
14880 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14890 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
148a0 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  > The SQLITE_CON
148b0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69  FIG_LOG option i
148c0 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
148d0 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a  ure the SQLite.*
148e0 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20  * global [error 
148f0 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53  log]..** (^The S
14900 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14910 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
14920 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
14930 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
14940 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
14950 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
14960 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
14970 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
14980 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
14990 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
149a0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
149b0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
149c0 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
149d0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
149e0 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
149f0 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
14a00 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
14a10 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
14a20 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
14a30 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
14a40 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
14a50 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
14a60 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
14a70 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
14a80 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
14a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
14aa0 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
14ab0 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
14ac0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
14ad0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
14ae0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
14af0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
14b00 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
14b10 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
14b20 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
14b30 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
14b40 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
14b50 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
14b60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
14b70 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
14b80 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
14b90 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
14ba0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
14bb0 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
14bc0 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
14bd0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
14be0 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
14bf0 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
14c00 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
14c10 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
14c20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
14c30 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
14c40 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
14c50 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
14c60 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
14c70 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
14c80 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
14c90 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
14ca0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
14cb0 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
14cc0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
14cd0 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
14ce0 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
14cf0 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
14d00 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
14d10 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
14d20 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
14d30 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
14d40 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14d50 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53  NFIG_URI]] <dt>S
14d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
14d70 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51  .** <dd>^(The SQ
14d80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
14d90 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14da0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
14db0 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49  f type int..** I
14dc0 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
14dd0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
14de0 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
14df0 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  d. If the parame
14e00 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20  ter is zero,.** 
14e10 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
14e20 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  g is globally di
14e30 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52  sabled.)^ ^If UR
14e40 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
14e50 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65  obally.** enable
14e60 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73  d, all filenames
14e70 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
14e80 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
14e90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
14ea0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ,.** [sqlite3_op
14eb0 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70  en16()] or.** sp
14ec0 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
14ed0 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d  of [ATTACH] comm
14ee0 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72  ands are interpr
14ef0 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65  eted as URIs, re
14f00 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77  gardless.** of w
14f10 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
14f20 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
14f30 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  RI] flag is set 
14f40 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
14f50 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
14f60 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69  is opened. ^If i
14f70 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
14f80 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
14f90 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
14fa0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
14fb0 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
14fc0 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
14fd0 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
14fe0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
14ff0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
15000 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52  ^(By default, UR
15010 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
15020 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c  obally.** disabl
15030 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ed. The default 
15040 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61  value may be cha
15050 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e  nged by compilin
15060 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  g with the.** [S
15070 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73  QLITE_USE_URI] s
15080 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e  ymbol defined.)^
15090 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
150a0 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
150b0 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74  INDEX_SCAN]] <dt
150c0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  >SQLITE_CONFIG_C
150d0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
150e0 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  AN.** <dd>^The S
150f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
15100 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
15110 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15120 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a  single integer.*
15130 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  * argument which
15140 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
15150 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20  as a boolean in 
15160 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20  order to enable 
15170 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  or disable.** th
15180 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
15190 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
151a0 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69  ll table scans i
151b0 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69  n the query opti
151c0 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64  mizer..** ^The d
151d0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69  efault setting i
151e0 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20  s determined.** 
151f0 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41  by the [SQLITE_A
15200 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  LLOW_COVERING_IN
15210 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c  DEX_SCAN] compil
15220 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f  e-time option, o
15230 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20  r is "on".** if 
15240 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  that compile-tim
15250 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74  e option is omit
15260 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c  ted..** The abil
15270 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ity to disable t
15280 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
15290 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
152a0 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a  ull table scans.
152b0 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f  ** is because so
152c0 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63  me incorrectly c
152d0 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c  oded legacy appl
152e0 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d  ications might m
152f0 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68  alfunction.** wh
15300 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  en the optimizat
15310 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20  ion is enabled. 
15320 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61   Providing the a
15330 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73  bility to.** dis
15340 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a  able the optimiz
15350 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65  ation allows the
15360 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70   older, buggy ap
15370 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74  plication code t
15380 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75  o work.** withou
15390 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69  t change even wi
153a0 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  th newer version
153b0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
153c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
153d0 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
153e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
153f0 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
15400 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15410 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
15420 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a  ONFIG_GETPCACHE.
15430 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
15440 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
15450 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
15460 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
15470 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
15480 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
15490 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
154a0 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
154b0 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
154c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
154d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
154e0 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  G]].** <dt>SQLIT
154f0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a  E_CONFIG_SQLLOG.
15500 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
15510 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
15520 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69  able if sqlite i
15530 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
15540 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
15550 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72  NABLE_SQLLOG] pr
15560 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
15570 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66  o defined. The f
15580 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68  irst argument sh
15590 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69  ould.** be a poi
155a0 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69  nter to a functi
155b0 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28  on of type void(
155c0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
155d0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  *,const char*, i
155e0 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  nt)..** The seco
155f0 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20  nd should be of 
15600 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68  type (void*). Th
15610 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
15620 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62  voked by the lib
15630 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65  rary.** in three
15640 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d   separate circum
15650 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66  stances, identif
15660 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65  ied by the value
15670 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a   passed as the.*
15680 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
15690 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74  er. If the fourt
156a0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30  h parameter is 0
156b0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
156c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
156d0 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
156e0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
156f0 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70  has just been op
15700 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20  ened. The third 
15710 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e  argument.** poin
15720 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63  ts to a buffer c
15730 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61  ontaining the na
15740 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64  me of the main d
15750 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66  atabase file. If
15760 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
15770 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74  arameter is 1, t
15780 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
15790 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74  ement that the t
157a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  hird parameter.*
157b0 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20  * points to has 
157c0 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74  just been execut
157d0 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66  ed. Or, if the f
157e0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
157f0 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  is 2, then.** th
15800 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69  e connection bei
15810 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ng passed as the
15820 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15830 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65  r is being close
15840 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  d. The.** third 
15850 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73  parameter is pas
15860 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73  sed NULL In this
15870 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70   case.  An examp
15880 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  le of using this
15890 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
158a0 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  n option can be 
158b0 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73  seen in the "tes
158c0 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72  t_sqllog.c" sour
158d0 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68  ce file in.** th
158e0 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69  e canonical SQLi
158f0 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c  te source tree.<
15900 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15910 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
15920 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
15930 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
15940 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51  _SIZE.** <dd>^SQ
15950 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
15960 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20  _SIZE takes two 
15970 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28  64-bit integer (
15980 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76  sqlite3_int64) v
15990 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72  alues.** that ar
159a0 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d  e the default mm
159b0 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74  ap size limit (t
159c0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
159d0 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d  ng for.** [PRAGM
159e0 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e  A mmap_size]) an
159f0 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  d the maximum al
15a00 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20  lowed mmap size 
15a10 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64  limit..** ^The d
15a20 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63  efault setting c
15a30 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
15a40 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73   by each databas
15a50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69  e connection usi
15a60 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65  ng.** either the
15a70 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
15a80 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20  ze] command, or 
15a90 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  by using the.** 
15aa0 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
15ab0 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
15ac0 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61  ntrol.  ^(The ma
15ad0 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
15ae0 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20  ap size.** will 
15af0 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  be silently trun
15b00 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61  cated if necessa
15b10 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f  ry so that it do
15b20 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68  es not exceed th
15b30 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  e.** compile-tim
15b40 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73  e maximum mmap s
15b50 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a  ize set by the.*
15b60 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d  * [SQLITE_MAX_MM
15b70 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65  AP_SIZE] compile
15b80 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a  -time option.)^.
15b90 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72  ** ^If either ar
15ba0 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f  gument to this o
15bb0 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76  ption is negativ
15bc0 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67  e, then that arg
15bd0 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e  ument is.** chan
15be0 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69  ged to its compi
15bf0 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e  le-time default.
15c00 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15c10 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
15c20 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PSIZE]].** <dt>S
15c30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
15c40 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c  32_HEAPSIZE.** <
15c50 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
15c60 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
15c70 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f  SIZE option is o
15c80 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
15c90 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
15ca0 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f  mpiled for Windo
15cb0 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ws with the [SQL
15cc0 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43  ITE_WIN32_MALLOC
15cd0 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
15ce0 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64  macro.** defined
15cf0 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  . ^SQLITE_CONFIG
15d00 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
15d10 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75  takes a 32-bit u
15d20 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
15d30 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70  value.** that sp
15d40 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69  ecifies the maxi
15d50 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20  mum size of the 
15d60 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a  created heap..**
15d70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15d80 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
15d90 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
15da0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
15db0 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  DRSZ.** <dd>^The
15dc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15dd0 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69  CACHE_HDRSZ opti
15de0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
15df0 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
15e00 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
15e10 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
15e20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20  and writes into 
15e30 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65  that integer the
15e40 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
15e50 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61  .** bytes per pa
15e60 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  ge required for 
15e70 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51  each page in [SQ
15e80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
15e90 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61  CACHE]..** The a
15ea0 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73  mount of extra s
15eb0 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61  pace required ca
15ec0 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69  n change dependi
15ed0 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ng on the compil
15ee0 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c  er,.** target pl
15ef0 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69  atform, and SQLi
15f00 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  te version..**.*
15f10 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15f20 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  G_PMASZ]].** <dt
15f30 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
15f40 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  MASZ.** <dd>^The
15f50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15f60 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  MASZ option take
15f70 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
15f80 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
15f90 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74   an unsigned int
15fa0 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68  eger and sets th
15fb0 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  e "Minimum PMA S
15fc0 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c  ize" for the mul
15fd0 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f  tithreaded.** so
15fe0 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74  rter to that int
15ff0 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75  eger.  The defau
16000 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  lt minimum PMA S
16010 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68  ize is set by th
16020 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52  e.** [SQLITE_SOR
16030 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69  TER_PMASZ] compi
16040 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20  le-time option. 
16050 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65   New threads are
16060 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20   launched.** to 
16070 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f  help with sort o
16080 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d  perations when m
16090 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72  ultithreaded sor
160a0 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c  ting.** is enabl
160b0 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50  ed (using the [P
160c0 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63  RAGMA threads] c
160d0 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20  ommand) and the 
160e0 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e  amount of conten
160f0 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65  t.** to be sorte
16100 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61  d exceeds the pa
16110 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68  ge size times th
16120 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65  e minimum of the
16130 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68  .** [PRAGMA cach
16140 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20  e_size] setting 
16150 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a  and this value..
16160 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
16170 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16180 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
16190 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
161a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
161b0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
161c0 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
161d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
161e0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
161f0 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
16200 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16210 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
16220 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
16230 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
16240 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16250 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
16260 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
16270 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
16280 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16290 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
162a0 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
162b0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
162c0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
162d0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
162e0 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
162f0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
16300 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
16310 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
16320 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
16330 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
16340 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
16350 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16360 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
16370 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
16380 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16390 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
163a0 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
163b0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
163c0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
163d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
163e0 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
163f0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
16400 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
16410 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
16420 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
16430 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
16440 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
16450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16460 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
16470 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
16480 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16490 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
164a0 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
164b0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
164c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
164d0 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
164e0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
164f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
16500 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
16510 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
16520 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16530 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
16540 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
16550 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16560 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16570 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
16580 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
16590 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
165a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
165b0 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
165c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
165d0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
165e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
165f0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
16600 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a  NDEX_SCAN 20  /*
16610 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16620 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
16630 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f  LLOG       21  /
16640 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a  * xSqllog, void*
16650 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16660 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
16670 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71  IZE    22  /* sq
16680 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c  lite3_int64, sql
16690 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64  ite3_int64 */.#d
166a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
166b0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
166c0 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69  ZE      23  /* i
166d0 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66  nt nByte */.#def
166e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
166f0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20  G_PCACHE_HDRSZ  
16700 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74        24  /* int
16710 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65   *psz */.#define
16720 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16730 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20  MASZ            
16740 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e     25  /* unsign
16750 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a  ed int szPma */.
16760 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16770 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
16780 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
16790 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
167a0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
167b0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
167c0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
167d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
167e0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
167f0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
16800 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
16810 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
16820 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
16830 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
16840 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16850 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
16860 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
16870 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
16880 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
16890 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
168a0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
168b0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
168c0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
168d0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
168e0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
168f0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
16900 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
16910 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
16920 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
16930 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
16940 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
16950 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
16960 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
16970 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
16980 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
16990 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
169a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
169b0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
169c0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
169d0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
169e0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
169f0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
16a00 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
16a10 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
16a20 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
16a30 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
16a40 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
16a50 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
16a60 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
16a70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16a80 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
16a90 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
16aa0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
16ab0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
16ac0 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
16ad0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
16ae0 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
16af0 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
16b00 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
16b10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
16b20 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
16b30 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
16b40 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
16b50 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
16b60 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
16b70 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
16b80 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
16b90 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
16ba0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16bb0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
16bc0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
16bd0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
16be0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
16bf0 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
16c00 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
16c10 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
16c20 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
16c30 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
16c40 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
16c50 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
16c60 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
16c70 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
16c80 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
16c90 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
16ca0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
16cb0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
16cc0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
16cd0 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
16ce0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
16cf0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
16d00 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
16d10 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
16d20 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
16d30 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
16d40 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
16d50 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
16d60 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
16d70 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
16d80 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
16d90 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
16da0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16db0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
16dc0 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
16dd0 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
16de0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
16df0 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
16e00 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
16e10 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
16e20 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
16e30 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
16e40 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
16e50 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
16e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
16e70 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
16e80 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
16e90 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
16ea0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
16eb0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
16ec0 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
16ed0 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
16ee0 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
16ef0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
16f00 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
16f10 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
16f20 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
16f30 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
16f40 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
16f50 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
16f60 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
16f70 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
16f80 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
16f90 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
16fa0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
16fb0 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
16fc0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
16fd0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
16fe0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
16ff0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
17000 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
17010 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
17020 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
17030 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
17040 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
17050 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
17060 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
17070 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
17080 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
17090 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
170a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
170b0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
170c0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
170d0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
170e0 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
170f0 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
17100 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
17110 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
17120 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
17130 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
17140 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
17150 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
17160 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
17170 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
17180 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
17190 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
171a0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
171b0 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
171c0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
171d0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
171e0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
171f0 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
17200 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
17210 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
17220 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
17230 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
17240 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
17250 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
17260 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
17270 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
17280 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
17290 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72  o enable trigger
172a0 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
172b0 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
172c0 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
172d0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
172e0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
172f0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
17300 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
17310 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
17320 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
17330 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72  ther triggers ar
17340 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  e disabled or en
17350 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
17360 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
17370 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17380 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
17390 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
173a0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
173b0 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20  trigger setting 
173c0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
173d0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
173e0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
173f0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
17400 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
17410 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
17420 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
17430 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
17440 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
17450 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e       1002  /* in
17460 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
17470 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
17480 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
17490 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69    1003  /* int i
174a0 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
174b0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
174c0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
174d0 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
174e0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
174f0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
17500 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
17510 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
17520 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
17530 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
17540 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
17550 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
17560 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
17570 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
17580 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
17590 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
175a0 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
175b0 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
175c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
175d0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
175e0 4c 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  L sqlite3_extend
175f0 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
17600 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
17610 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
17620 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
17630 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48  rt Rowid.** METH
17640 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
17650 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
17660 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62   most SQLite tab
17670 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20  les (except for 
17680 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
17690 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61  tables).** has a
176a0 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
176b0 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
176c0 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
176d0 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
176e0 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73  ]. ^The rowid is
176f0 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
17700 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
17710 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
17720 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
17730 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
17740 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
17750 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
17760 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
17770 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
17780 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65  umns. ^If.** the
17790 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
177a0 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
177b0 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
177c0 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
177d0 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
177e0 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
177f0 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  owid..**.** ^The
17800 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
17810 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e  sert_rowid(D) in
17820 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
17830 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
17840 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  he .** most rece
17850 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  nt successful [I
17860 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f  NSERT] into a ro
17870 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69  wid table or [vi
17880 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
17890 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  on database conn
178a0 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e  ection D..** ^In
178b0 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48  serts into [WITH
178c0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
178d0 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64  s are not record
178e0 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75  ed..** ^If no su
178f0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
17900 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61  ]s into rowid ta
17910 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  bles.** have eve
17920 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
17930 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17940 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65  ction D, .** the
17950 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  n sqlite3_last_i
17960 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72  nsert_rowid(D) r
17970 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
17980 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
17990 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
179a0 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77  n a trigger or w
179b0 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c  ithin a [virtual
179c0 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f   table].** metho
179d0 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  d, then this rou
179e0 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
179f0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
17a00 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
17a10 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  row as long as t
17a20 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
17a30 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
17a40 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  od is running..*
17a50 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
17a60 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
17a70 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65  l table method e
17a80 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
17a90 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
17aa0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
17ab0 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
17ac0 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
17ad0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
17ae0 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  .** table method
17af0 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20   began.)^.**.** 
17b00 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
17b10 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
17b20 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
17b30 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
17b40 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
17b50 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
17b60 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
17b70 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
17b80 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
17b90 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
17ba0 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
17bb0 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
17bc0 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
17bd0 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
17be0 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
17bf0 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
17c00 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
17c10 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
17c20 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
17c30 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
17c40 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
17c50 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
17c60 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
17c70 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
17c80 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
17c90 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
17ca0 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
17cb0 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
17cc0 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
17cd0 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
17ce0 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
17cf0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
17d00 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
17d10 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
17d20 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
17d30 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
17d40 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
17d50 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
17d60 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
17d70 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
17d80 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
17d90 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
17da0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
17db0 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
17dc0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
17dd0 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
17de0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
17df0 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
17e00 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
17e10 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
17e20 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
17e30 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
17e40 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
17e50 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
17e60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17e70 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
17e80 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
17e90 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
17ea0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
17eb0 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
17ec0 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
17ed0 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
17ee0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
17ef0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
17f00 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
17f10 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
17f20 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
17f30 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
17f40 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
17f50 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
17f60 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
17f70 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
17f80 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53   sqlite3_int64 S
17f90 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
17fa0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17fb0 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
17fc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17fd0 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
17fe0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
17ff0 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ified.** METHOD:
18000 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
18010 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
18020 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
18030 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
18040 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a  d, inserted or.*
18050 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  * deleted by the
18060 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
18070 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
18080 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
18090 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f  E.** statement o
180a0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
180b0 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66  onnection specif
180c0 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20  ied by the only 
180d0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45  parameter..** ^E
180e0 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
180f0 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
18100 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
18110 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c  t modify the val
18120 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
18130 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  y this function.
18140 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61  .**.** ^Only cha
18150 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74  nges made direct
18160 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54  ly by the INSERT
18170 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
18180 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
18190 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d  .** considered -
181a0 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   auxiliary chang
181b0 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52  es caused by [CR
181c0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
181d0 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66  riggers], .** [f
181e0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
181f0 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d  ns] or [REPLACE]
18200 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
18210 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63  lution are not c
18220 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43  ounted..** .** C
18230 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
18240 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
18250 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e  epted by .** [IN
18260 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
18270 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72   | INSTEAD OF tr
18280 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20  iggers] are not 
18290 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61  counted. ^The va
182a0 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64  lue .** returned
182b0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
182c0 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c  ges() immediatel
182d0 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52  y after an INSER
182e0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a  T, UPDATE or .**
182f0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
18300 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20  t run on a view 
18310 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20  is always zero. 
18320 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
18330 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61  e to real .** ta
18340 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  bles are counted
18350 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61  ..**.** Things a
18360 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61  re more complica
18370 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74  ted if the sqlit
18380 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
18390 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63  ction is.** exec
183a0 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69  uted while a tri
183b0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20  gger program is 
183c0 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61  running. This ma
183d0 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a  y happen if the.
183e0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  ** program uses 
183f0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
18400 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72  QL function], or
18410 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63   if some other c
18420 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
18430 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69  ion invokes sqli
18440 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69  te3_changes() di
18450 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61  rectly. Essentia
18460 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e  lly:.** .** <ul>
18470 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66  .**   <li> ^(Bef
18480 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74  ore entering a t
18490 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74  rigger program t
184a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
184b0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73  d by.**        s
184c0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
184d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76   function is sav
184e0 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72  ed. After the tr
184f0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a  igger program .*
18500 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e  *        has fin
18510 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69  ished, the origi
18520 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73  nal value is res
18530 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20  tored.)^.** .** 
18540 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20    <li> ^(Within 
18550 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
18560 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55  m each INSERT, U
18570 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45  PDATE and DELETE
18580 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74   .**        stat
18590 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76  ement sets the v
185a0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
185b0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
185c0 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70  () .**        up
185d0 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73  on completion as
185e0 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72   normal. Of cour
185f0 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77  se, this value w
18600 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  ill not include 
18610 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63  .**        any c
18620 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64  hanges performed
18630 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73   by sub-triggers
18640 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33  , as the sqlite3
18650 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
18660 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c        value will
18670 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65   be saved and re
18680 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63  stored after eac
18690 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61  h sub-trigger ha
186a0 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c  s run.)^.** </ul
186b0 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d  >.** .** ^This m
186c0 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65  eans that if the
186d0 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66   changes() SQL f
186e0 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69  unction (or simi
186f0 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20  lar) is used.** 
18700 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53  by the first INS
18710 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
18720 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
18730 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
18740 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73  , it .** returns
18750 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65   the value as se
18760 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69  t when the calli
18770 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67  ng statement beg
18780 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  an executing..**
18790 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20   ^If it is used 
187a0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72  by the second or
187b0 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68   subsequent such
187c0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
187d0 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20  n a trigger .** 
187e0 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c  program, the val
187f0 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c  ue returned refl
18800 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20  ects the number 
18810 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
18820 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76   by the .** prev
18830 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44  ious INSERT, UPD
18840 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
18850 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
18860 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
18870 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
18880 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
18890 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
188a0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
188b0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
188c0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
188d0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
188e0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
188f0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
18900 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
18910 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
18920 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18930 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
18940 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
18950 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
18960 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
18970 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
18980 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
18990 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
189a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
189b0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
189c0 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
189d0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
189e0 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
189f0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
18a00 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ified.** METHOD:
18a10 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
18a20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
18a30 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20  turns the total 
18a40 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69  number of rows i
18a50 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65  nserted, modifie
18a60 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d or.** deleted 
18a70 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c  by all [INSERT],
18a80 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
18a90 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
18aa0 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69   completed.** si
18ab0 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nce the database
18ac0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20   connection was 
18ad0 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e  opened, includin
18ae0 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65 64  g those executed
18af0 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74   as.** part of t
18b00 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e  rigger programs.
18b10 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20   ^Executing any 
18b20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51  other type of SQ
18b30 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64  L statement.** d
18b40 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74  oes not affect t
18b50 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
18b60 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74  d by sqlite3_tot
18b70 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a  al_changes()..**
18b80 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61   .** ^Changes ma
18b90 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66  de as part of [f
18ba0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
18bb0 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64  ns] are included
18bc0 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74   in the.** count
18bd0 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65  , but those made
18be0 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c   as part of REPL
18bf0 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  ACE constraint r
18c00 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a  esolution are.**
18c10 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74   not. ^Changes t
18c20 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
18c30 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79  e intercepted by
18c40 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
18c50 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74  gers .** are not
18c60 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
18c70 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
18c80 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
18c90 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
18ca0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
18cb0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
18cc0 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67  the [total_chang
18cd0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
18ce0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
18cf0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
18d00 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
18d10 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
18d20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
18d30 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
18d40 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
18d50 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
18d60 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
18d70 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
18d80 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
18d90 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
18da0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
18db0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
18dc0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
18dd0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
18de0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
18df0 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
18e00 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20  unning Query.** 
18e10 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
18e20 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
18e30 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
18e40 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
18e50 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
18e60 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
18e70 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
18e80 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
18e90 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
18ea0 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
18eb0 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
18ec0 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
18ed0 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
18ee0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
18ef0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
18f00 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
18f10 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
18f20 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
18f30 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
18f40 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
18f50 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
18f60 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
18f70 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
18f80 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
18f90 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
18fa0 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
18fb0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
18fc0 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
18fd0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
18fe0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
18ff0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
19000 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
19010 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
19020 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
19030 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
19040 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
19050 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
19060 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
19070 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
19080 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
19090 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
190a0 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
190b0 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
190c0 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
190d0 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
190e0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
190f0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
19100 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
19110 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
19120 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
19130 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
19140 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
19150 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
19160 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
19170 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
19180 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
19190 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
191a0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
191b0 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
191c0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
191d0 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
191e0 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
191f0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
19200 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
19210 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
19220 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
19230 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
19240 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
19250 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
19260 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
19270 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
19280 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
19290 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
192a0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
192b0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
192c0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
192d0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
192e0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
192f0 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
19300 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
19310 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
19320 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
19330 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
19340 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
19350 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
19360 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
19370 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
19380 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
19390 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
193a0 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
193b0 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
193c0 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
193d0 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
193e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
193f0 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
19400 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
19410 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
19420 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
19430 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
19440 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
19450 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
19460 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
19470 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
19480 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
19490 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
194a0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
194b0 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
194c0 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
194d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
194e0 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
194f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
19500 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20  ].** is running 
19510 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
19520 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
19530 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  en..*/.SQLITE_AP
19540 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  I void SQLITE_ST
19550 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 69 6e  DCALL sqlite3_in
19560 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
19570 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19580 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
19590 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
195a0 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
195b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
195c0 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
195d0 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
195e0 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
195f0 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
19600 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
19610 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
19620 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
19630 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
19640 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
19650 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
19660 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
19670 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
19680 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
19690 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
196a0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
196b0 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
196c0 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
196d0 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
196e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
196f0 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
19700 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
19710 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
19720 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
19730 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
19740 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
19750 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
19760 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
19770 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
19780 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
19790 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
197a0 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
197b0 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
197c0 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
197d0 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
197e0 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
197f0 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
19800 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
19810 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
19820 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
19830 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
19840 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
19850 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
19860 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
19870 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
19880 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
19890 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
198a0 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
198b0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
198c0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
198d0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
198e0 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
198f0 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
19900 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
19910 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
19920 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
19930 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
19940 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
19950 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
19960 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
19970 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
19980 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
19990 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
199a0 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
199b0 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
199c0 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
199d0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
199e0 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
199f0 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
19a00 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
19a10 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
19a20 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
19a30 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
19a40 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
19a50 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
19a60 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
19a70 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
19a80 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
19a90 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
19aa0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
19ab0 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
19ac0 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
19ad0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
19ae0 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
19af0 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
19b00 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
19b10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
19b20 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
19b30 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
19b40 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
19b50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
19b60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
19b70 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
19b80 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
19b90 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
19ba0 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
19bb0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53  byte order..*/.S
19bc0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
19bd0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
19be0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
19bf0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
19c00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
19c10 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
19c20 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
19c30 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
19c40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19c50 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
19c60 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
19c70 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
19c80 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  rors.** KEYWORDS
19c90 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20  : {busy-handler 
19ca0 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20  callback} {busy 
19cb0 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48  handler}.** METH
19cc0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
19cd0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
19ce0 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c  usy_handler(D,X,
19cf0 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  P) routine sets 
19d00 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
19d10 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69  ion X.** that mi
19d20 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
19d30 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
19d40 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
19d50 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
19d60 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61   access a databa
19d70 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61  se table associa
19d80 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74  ted with.** [dat
19d90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19da0 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72  ] D when another
19db0 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
19dc0 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61  ocess has the ta
19dd0 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54  ble locked..** T
19de0 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
19df0 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66  handler() interf
19e00 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69  ace is used to i
19e10 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c  mplement.** [sql
19e20 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
19e30 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41  t()] and [PRAGMA
19e40 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a   busy_timeout]..
19e50 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
19e60 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
19e70 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
19e80 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65  E_BUSY].** is re
19e90 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
19ea0 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
19eb0 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
19ec0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
19ed0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
19ee0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
19ef0 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
19f00 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
19f10 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
19f20 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
19f30 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
19f40 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
19f50 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
19f60 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
19f70 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
19f80 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
19f90 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
19fa0 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
19fb0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
19fc0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19fd0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
19fe0 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
19ff0 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
1a000 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
1a010 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69  en invoked previ
1a020 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61  ously for the sa
1a030 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
1a040 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
1a050 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
1a060 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
1a070 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
1a080 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
1a090 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
1a0a0 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
1a0b0 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72  E_BUSY] is retur
1a0c0 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  ned.** to the ap
1a0d0 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  plication..** ^I
1a0e0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
1a0f0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1a100 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
1a110 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
1a120 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
1a130 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20  atabase and the 
1a140 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
1a150 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
1a160 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
1a170 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
1a180 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
1a190 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
1a1a0 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
1a1b0 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
1a1c0 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
1a1d0 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
1a1e0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
1a1f0 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
1a200 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
1a210 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
1a220 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
1a230 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1a240 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1a250 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20  tion instead of 
1a260 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a  invoking the .**
1a270 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1a280 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
1a290 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
1a2a0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1a2b0 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
1a2c0 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
1a2d0 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
1a2e0 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
1a2f0 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
1a300 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
1a310 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
1a320 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
1a330 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
1a340 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
1a350 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
1a360 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
1a370 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
1a380 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1a390 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
1a3a0 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
1a3b0 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
1a3c0 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
1a3d0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1a3e0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
1a3f0 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
1a400 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
1a410 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
1a420 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
1a430 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
1a440 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
1a450 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
1a460 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
1a470 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1a480 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
1a490 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
1a4a0 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
1a4b0 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
1a4c0 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
1a4d0 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
1a4e0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
1a4f0 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
1a500 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
1a510 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1a520 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ULL..**.** ^(The
1a530 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1a540 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1a550 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
1a560 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
1a570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1a580 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
1a590 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
1a5a0 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
1a5b0 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
1a5c0 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
1a5d0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1a5e0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1a5f0 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  .** or evaluatin
1a600 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  g [PRAGMA busy_t
1a610 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63  imeout=N] will c
1a620 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73  hange the.** bus
1a630 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68  y handler and th
1a640 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65  us clear any pre
1a650 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79  viously set busy
1a660 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
1a670 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
1a680 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
1a690 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
1a6a0 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
1a6b0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1a6c0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1a6d0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1a6e0 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ler.  In other w
1a6f0 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73  ords,.** the bus
1a700 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74  y handler is not
1a710 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79   reentrant.  Any
1a720 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
1a730 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
1a740 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
1a750 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
1a760 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
1a770 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
1a780 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1a790 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
1a7a0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
1a7b0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1a7c0 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  dler..*/.SQLITE_
1a7d0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
1a7e0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
1a7f0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1a800 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
1a810 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
1a820 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a830 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
1a840 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eout.** METHOD: 
1a850 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1a860 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
1a870 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
1a880 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
1a890 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
1a8a0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
1a8b0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
1a8c0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
1a8d0 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
1a8e0 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
1a8f0 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
1a900 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
1a910 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1a920 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1a930 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
1a940 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
1a950 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
1a960 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1a970 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
1a980 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
1a990 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
1a9a0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
1a9b0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
1a9c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
1a9d0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68  *.** ^Calling th
1a9e0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1a9f0 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
1aa00 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
1aa10 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
1aa20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
1aa30 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dlers..**.** ^(T
1aa40 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1aa50 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1aa60 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
1aa70 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1aa80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1aa90 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f   at any given mo
1aaa0 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
1aab0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
1aac0 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
1aad0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
1aae0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
1aaf0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
1ab00 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
1ab10 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
1ab20 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
1ab30 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  ared.)^.**.** Se
1ab40 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41  e also:  [PRAGMA
1ab50 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a   busy_timeout].*
1ab60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1ab70 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1ab80 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1ab90 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
1aba0 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
1abb0 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
1abc0 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
1abd0 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
1abe0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
1abf0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ite3.**.** This 
1ac00 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
1ac10 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
1ac20 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
1ac30 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1ac40 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
1ac50 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
1ac60 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
1ac70 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
1ac80 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
1ac90 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
1aca0 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
1acb0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
1acc0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
1acd0 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
1ace0 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
1acf0 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
1ad00 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
1ad10 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
1ad20 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
1ad30 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
1ad40 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
1ad50 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
1ad60 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
1ad70 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
1ad80 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
1ad90 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
1ada0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
1adb0 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
1adc0 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
1add0 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
1ade0 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
1adf0 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
1ae00 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
1ae10 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
1ae20 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1ae30 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
1ae40 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
1ae50 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1ae60 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
1ae70 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
1ae80 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
1ae90 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
1aea0 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
1aeb0 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
1aec0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1aed0 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
1aee0 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
1aef0 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
1af00 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
1af10 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
1af20 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
1af30 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
1af40 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
1af50 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
1af60 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
1af70 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
1af80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1af90 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
1afa0 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
1afb0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1afc0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
1afd0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1afe0 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
1aff0 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
1b000 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
1b010 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
1b020 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
1b030 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
1b040 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
1b050 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
1b060 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
1b070 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
1b080 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
1b090 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1b0a0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
1b0b0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
1b0c0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
1b0d0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
1b0e0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
1b0f0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1b100 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1b110 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1b120 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
1b130 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
1b140 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1b150 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
1b160 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
1b170 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
1b180 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
1b190 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
1b1a0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
1b1b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1b1c0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
1b1d0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
1b1e0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
1b1f0 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
1b200 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
1b210 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
1b220 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
1b230 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
1b240 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
1b250 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
1b260 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
1b270 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
1b280 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
1b290 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b2a0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1b2b0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
1b2c0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b2d0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
1b2e0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b2f0 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
1b300 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
1b310 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
1b320 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
1b330 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b340 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
1b350 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1b360 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
1b370 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b380 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
1b390 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
1b3a0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
1b3b0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
1b3c0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
1b3d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1b3e0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
1b3f0 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
1b400 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1b410 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
1b420 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1b430 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
1b440 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
1b450 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
1b460 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
1b470 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
1b480 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
1b490 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
1b4a0 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
1b4b0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
1b4c0 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
1b4d0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
1b4e0 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
1b4f0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
1b500 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
1b510 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
1b520 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
1b530 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
1b540 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
1b550 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
1b560 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
1b570 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
1b580 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
1b590 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
1b5a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
1b5b0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
1b5c0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1b5d0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
1b5e0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
1b5f0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
1b600 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1b610 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
1b620 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1b630 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
1b640 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
1b650 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
1b660 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
1b670 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1b680 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
1b690 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
1b6a0 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
1b6b0 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
1b6c0 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
1b6d0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1b6e0 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
1b6f0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
1b700 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
1b710 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
1b720 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
1b730 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
1b740 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
1b750 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
1b760 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
1b770 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
1b780 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
1b790 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
1b7a0 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
1b7b0 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
1b7c0 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
1b7d0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
1b7e0 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
1b7f0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
1b800 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1b810 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1b820 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51  errmsg()]..*/.SQ
1b830 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
1b840 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1b850 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1b860 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1b870 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1b880 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1b890 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1b8a0 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1b8b0 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1b8c0 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1b8d0 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1b8e0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1b8f0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1b900 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1b910 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1b920 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1b930 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1b940 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1b950 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1b960 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1b970 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1b980 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1b990 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1b9a0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1b9b0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1b9c0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1b9d0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1b9e0 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
1b9f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ba00 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
1ba10 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
1ba20 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1ba30 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1ba40 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
1ba50 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
1ba60 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
1ba70 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
1ba80 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1ba90 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
1baa0 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d  nes understand m
1bab0 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f  ost of the commo
1bac0 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67  n K&R formatting
1bad0 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75   options,.** plu
1bae0 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  s some additiona
1baf0 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66  l non-standard f
1bb00 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64  ormats, detailed
1bb10 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20   below..** Note 
1bb20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65  that some of the
1bb30 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f   more obscure fo
1bb40 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1bb50 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20   from recent.** 
1bb60 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61  C-library standa
1bb70 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20  rds are omitted 
1bb80 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d  from this implem
1bb90 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  entation..**.** 
1bba0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1bbb0 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1bbc0 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1bbd0 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1bbe0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1bbf0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1bc00 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1bc10 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1bc20 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1bc30 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1bc40 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1bc50 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1bc60 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1bc70 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1bc80 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1bc90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1bca0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1bcb0 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1bcc0 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1bcd0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1bce0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1bcf0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1bd00 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1bd10 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1bd20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1bd30 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1bd40 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1bd50 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1bd60 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1bd70 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1bd80 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1bd90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1bda0 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1bdb0 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1bdc0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1bdd0 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1bde0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1bdf0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1be00 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1be10 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1be20 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1be30 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1be40 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1be50 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1be60 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1be70 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1be80 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1be90 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1bea0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1beb0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1bec0 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1bed0 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1bee0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1bef0 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1bf00 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1bf10 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1bf20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1bf30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1bf40 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1bf50 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1bf60 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1bf70 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1bf80 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1bf90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1bfa0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1bfb0 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1bfc0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1bfd0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1bfe0 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1bff0 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1c000 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1c010 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1c020 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1c030 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1c040 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1c050 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1c060 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1c070 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1c080 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1c090 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1c0a0 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1c0b0 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1c0c0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1c0d0 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1c0e0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1c0f0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1c100 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1c110 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1c120 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c130 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1c140 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1c150 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1c160 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1c170 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1c180 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1c190 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1c1a0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1c1b0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1c1c0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1c1d0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1c1e0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1c1f0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1c200 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1c210 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1c220 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1c230 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1c240 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20  %q", "%Q", "%w" 
1c250 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1c260 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1c270 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1c280 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1c290 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1c2a0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1c2b0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1c2c0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1c2d0 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1c2e0 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1c2f0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1c300 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1c310 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1c320 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1c330 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1c340 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1c350 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1c360 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1c370 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1c380 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1c390 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1c3a0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1c3b0 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1c3c0 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1c3d0 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1c3e0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1c3f0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1c400 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1c410 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1c420 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1c430 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1c440 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1c450 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1c460 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1c470 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1c480 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1c490 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1c4a0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1c4b0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1c4c0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1c4d0 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1c4e0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1c4f0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1c500 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1c510 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1c520 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1c530 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1c540 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1c550 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1c560 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1c570 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1c580 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1c590 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1c5a0 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1c5b0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1c5c0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1c5d0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1c5e0 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1c5f0 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1c600 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1c610 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1c620 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1c630 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1c640 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1c650 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1c660 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1c670 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1c680 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1c690 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1c6a0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1c6b0 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1c6c0 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1c6d0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1c6e0 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1c6f0 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1c700 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1c710 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1c720 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1c730 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1c740 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1c750 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1c760 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1c770 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1c780 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1c790 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1c7a0 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1c7b0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1c7c0 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1c7d0 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1c7e0 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1c7f0 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1c800 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1c810 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1c820 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1c830 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1c840 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1c850 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1c860 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1c870 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1c880 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1c890 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1c8a0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1c8b0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1c8c0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1c8d0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1c8e0 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1c8f0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1c900 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1c910 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1c920 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1c930 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1c940 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1c950 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1c960 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1c970 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1c980 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1c990 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1c9a0 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1c9b0 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1c9c0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1c9d0 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1c9e0 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b  ng option is lik
1c9f0 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74 68  e "%q" except th
1ca00 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74 6f  at it expects to
1ca10 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  .** be contained
1ca20 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71   within double-q
1ca30 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66  uotes instead of
1ca40 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20   single quotes, 
1ca50 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65  and it.** escape
1ca60 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f  s the double-quo
1ca70 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e 73  te character ins
1ca80 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67  tead of the sing
1ca90 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72  le-quote.** char
1caa0 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25  acter.)^  The "%
1cab0 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  w" formatting op
1cac0 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64  tion is intended
1cad0 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65   for safely inse
1cae0 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61  rting.** table a
1caf0 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  nd column names 
1cb00 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74  into a construct
1cb10 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1cb20 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1cb30 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1cb40 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1cb50 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1cb60 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1cb70 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1cb80 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1cb90 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1cba0 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1cbb0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1cbc0 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1cbd0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1cbe0 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
1cbf0 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 43 44   char *SQLITE_CD
1cc00 45 43 4c 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  ECL sqlite3_mpri
1cc10 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1cc20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ...);.SQLITE_API
1cc30 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
1cc40 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 6d  DCALL sqlite3_vm
1cc50 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1cc60 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51  r*, va_list);.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 43 44 45 43 4c 20 73 71 6c 69  QLITE_CDECL sqli
1cc90 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
1cca0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1ccb0 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  r*, ...);.SQLITE
1ccc0 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54  _API char *SQLIT
1ccd0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1cce0 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
1ccf0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1cd00 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
1cd10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1cd20 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
1cd30 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
1cd40 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
1cd50 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
1cd60 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
1cd70 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
1cd80 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
1cd90 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
1cda0 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
1cdb0 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
1cdc0 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
1cdd0 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
1cde0 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
1cdf0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
1ce00 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
1ce10 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
1ce20 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
1ce30 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
1ce40 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
1ce50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1ce60 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
1ce70 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1ce80 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
1ce90 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
1cea0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
1ceb0 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
1cec0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
1ced0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1cee0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
1cef0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
1cf00 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
1cf10 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
1cf20 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1cf30 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
1cf40 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
1cf50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1cf60 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
1cf70 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
1cf80 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
1cf90 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
1cfa0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
1cfb0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1cfc0 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73  N) routine works
1cfd0 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71   just like.** sq
1cfe0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
1cff0 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73  except that N is
1d000 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d   an unsigned 64-
1d010 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74  bit integer inst
1d020 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e  ead.** of a sign
1d030 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  ed 32-bit intege
1d040 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
1d050 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
1d060 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
1d070 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
1d080 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1d090 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1d0a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1d0b0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
1d0c0 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
1d0d0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
1d0e0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1d0f0 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
1d100 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
1d110 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
1d120 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1d130 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
1d140 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
1d150 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1d160 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
1d170 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
1d180 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
1d190 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
1d1a0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
1d1b0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
1d1c0 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
1d1d0 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
1d1e0 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
1d1f0 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
1d200 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1d210 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
1d220 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
1d230 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
1d240 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1d250 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
1d260 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
1d270 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
1d280 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
1d290 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
1d2a0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
1d2b0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
1d2c0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1d2d0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
1d2e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1d2f0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74  realloc(X,N) int
1d300 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
1d310 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
1d320 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
1d330 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61  cation X to be a
1d340 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e  t least N bytes.
1d350 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61  .** ^If the X pa
1d360 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1d370 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a  e3_realloc(X,N).
1d380 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
1d390 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
1d3a0 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
1d3b0 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
1d3c0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1d3d0 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  (N)..** ^If the 
1d3e0 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  N parameter to s
1d3f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1d400 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  ,N) is zero or.*
1d410 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
1d420 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1d430 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
1d440 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
1d450 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a  qlite3_free(X)..
1d460 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c  ** ^sqlite3_real
1d470 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1d480 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1d490 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d4a0 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
1d4b0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
1d4c0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75   or NULL if insu
1d4d0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
1d4e0 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
1d4f0 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
1d500 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
1d510 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
1d520 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
1d530 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
1d540 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
1d550 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
1d560 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
1d570 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
1d580 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
1d590 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70  c(X,N) and the p
1d5a0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1d5b0 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
1d5c0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d5d0 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55  (X,N) returns NU
1d5e0 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69  LL and N is posi
1d5f0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a  tive, then the.*
1d600 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  * prior allocati
1d610 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  on is not freed.
1d620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1d630 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c  te3_realloc64(X,
1d640 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f  N) interfaces wo
1d650 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a  rks the same as.
1d660 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ** sqlite3_reall
1d670 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74  oc(X,N) except t
1d680 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69  hat N is a 64-bi
1d690 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
1d6a0 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  er instead.** of
1d6b0 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64   a 32-bit signed
1d6c0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
1d6d0 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72  ^If X is a memor
1d6e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65  y allocation pre
1d6f0 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
1d700 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
1d710 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
1d720 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73  e3_malloc64(), s
1d730 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d740 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  , or sqlite3_rea
1d750 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a  lloc64(), then.*
1d760 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
1d770 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  X) returns the s
1d780 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f  ize of that memo
1d790 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e  ry allocation in
1d7a0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20   bytes..** ^The 
1d7b0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1d7c0 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  y sqlite3_msize(
1d7d0 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67  X) might be larg
1d7e0 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62  er than the numb
1d7f0 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72  er.** of bytes r
1d800 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20  equested when X 
1d810 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20  was allocated.  
1d820 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20  ^If X is a NULL 
1d830 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20  pointer then.** 
1d840 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1d850 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20   returns zero.  
1d860 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73  If X points to s
1d870 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73  omething that is
1d880 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69   not.** the begi
1d890 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20  nning of memory 
1d8a0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69  allocation, or i
1d8b0 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  f it points to a
1d8c0 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c   formerly.** val
1d8d0 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  id memory alloca
1d8e0 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f  tion that has no
1d8f0 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68  w been freed, th
1d900 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
1d910 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73  ** of sqlite3_ms
1d920 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69  ize(X) is undefi
1d930 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79  ned and possibly
1d940 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
1d950 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75  ^The memory retu
1d960 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1d970 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65  malloc(), sqlite
1d980 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20  3_realloc(),.** 
1d990 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1d9a0 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
1d9b0 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69  realloc64().** i
1d9c0 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
1d9d0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
1d9e0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
1d9f0 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
1da00 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
1da10 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
1da20 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
1da30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
1da40 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
1da50 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
1da60 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
1da70 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
1da80 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
1da90 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
1daa0 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
1dab0 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
1dac0 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
1dad0 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
1dae0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
1daf0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
1db00 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
1db10 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
1db20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
1db30 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
1db40 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1db50 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
1db60 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  sed..**.** Prior
1db70 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
1db80 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57  on 3.7.10, the W
1db90 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
1dba0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64  ace layer called
1dbb0 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
1dbc0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1dbd0 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
1dbe0 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
1dbf0 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
1dc00 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
1dc10 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
1dc20 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
1dc30 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
1dc40 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
1dc50 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
1dc60 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
1dc70 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
1dc80 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
1dc90 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c  s were detected,
1dca0 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72   but.** they wer
1dcb0 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
1dcc0 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
1dcd0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
1dce0 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
1dcf0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
1dd00 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
1dd10 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
1dd20 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
1dd30 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
1dd40 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1dd50 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
1dd60 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
1dd70 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
1dd80 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
1dd90 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
1dda0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1ddb0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1ddc0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
1ddd0 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
1dde0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
1ddf0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1de00 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
1de10 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
1de20 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
1de30 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
1de40 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
1de50 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
1de60 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
1de70 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1de80 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  c()]..*/.SQLITE_
1de90 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  API void *SQLITE
1dea0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1deb0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51  _malloc(int);.SQ
1dec0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53  LITE_API void *S
1ded0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1dee0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73  lite3_malloc64(s
1def0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1df00 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1df10 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
1df20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1df30 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  void*, int);.SQL
1df40 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51  ITE_API void *SQ
1df50 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1df60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76  ite3_realloc64(v
1df70 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
1df80 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
1df90 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  I void SQLITE_ST
1dfa0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72  DCALL sqlite3_fr
1dfb0 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ee(void*);.SQLIT
1dfc0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 75 69  E_API sqlite3_ui
1dfd0 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43  nt64 SQLITE_STDC
1dfe0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  ALL sqlite3_msiz
1dff0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
1e000 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1e010 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
1e020 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
1e030 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
1e040 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
1e050 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
1e060 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
1e070 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
1e080 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
1e090 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
1e0a0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1e0b0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
1e0c0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
1e0d0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
1e0e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
1e0f0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
1e100 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1e110 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
1e120 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
1e130 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
1e140 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
1e150 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
1e160 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
1e170 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
1e180 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1e190 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1e1a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1e1b0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
1e1c0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
1e1d0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1e1e0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
1e1f0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
1e200 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
1e210 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
1e220 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1e230 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
1e240 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
1e250 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1e260 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
1e270 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
1e280 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
1e290 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1e2a0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1e2b0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
1e2c0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
1e2d0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
1e2e0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
1e2f0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
1e300 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
1e310 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
1e320 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
1e330 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
1e340 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
1e350 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
1e360 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
1e370 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1e380 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
1e390 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1e3a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
1e3b0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1e3c0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
1e3d0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1e3e0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1e3f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1e400 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
1e410 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
1e420 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
1e430 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
1e440 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53   sqlite3_int64 S
1e450 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1e460 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1e470 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  d(void);.SQLITE_
1e480 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
1e490 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  4 SQLITE_STDCALL
1e4a0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1e4b0 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
1e4c0 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
1e4d0 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
1e4e0 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
1e4f0 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
1e500 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
1e510 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
1e520 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
1e530 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
1e540 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
1e550 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
1e560 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
1e570 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
1e580 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
1e590 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
1e5a0 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
1e5b0 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
1e5c0 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
1e5d0 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
1e5e0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
1e5f0 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
1e600 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
1e610 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
1e620 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
1e630 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
1e640 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
1e650 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
1e660 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
1e670 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
1e680 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
1e690 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
1e6a0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
1e6b0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54   buffer P..** ^T
1e6c0 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63  he P parameter c
1e6d0 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  an be a NULL poi
1e6e0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  nter..**.** ^If 
1e6f0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73  this routine has
1e700 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f   not been previo
1e710 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69  usly called or i
1e720 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a  f the previous.*
1e730 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73  * call had N les
1e740 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20  s than one or a 
1e750 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
1e760 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e   P, then the PRN
1e770 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75  G is.** seeded u
1e780 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
1e790 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68  obtained from th
1e7a0 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
1e7b0 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64  thod of.** the d
1e7c0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1e7d0 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
1e7e0 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73  ^If the previous
1e7f0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
1e800 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f  utine had an N o
1e810 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20  f 1 or more and 
1e820 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20  a.** non-NULL P 
1e830 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d  then the pseudo-
1e840 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
1e850 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
1e860 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
1e870 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
1e880 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
1e890 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
1e8a0 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ethod..*/.SQLITE
1e8b0 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
1e8c0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1e8d0 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
1e8e0 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
1e8f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1e900 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
1e910 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
1e920 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
1e930 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1e940 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
1e950 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
1e960 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
1e970 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1e980 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1e990 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
1e9a0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
1e9b0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
1e9c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e9d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
1e9e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1e9f0 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
1ea00 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1ea10 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1ea20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
1ea30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1ea40 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1ea50 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
1ea60 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
1ea70 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
1ea80 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
1ea90 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
1eaa0 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
1eab0 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
1eac0 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
1ead0 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
1eae0 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
1eaf0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1eb00 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
1eb10 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
1eb20 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
1eb30 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
1eb40 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1eb50 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
1eb60 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
1eb70 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
1eb80 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
1eb90 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
1eba0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
1ebb0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
1ebc0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1ebd0 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
1ebe0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
1ebf0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1ec00 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
1ec10 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
1ec20 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
1ec30 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
1ec40 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
1ec50 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ec60 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
1ec70 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
1ec80 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
1ec90 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
1eca0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1ecb0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
1ecc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1ecd0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1ece0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1ecf0 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
1ed00 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1ed10 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1ed20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
1ed30 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1ed40 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1ed50 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
1ed60 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
1ed70 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
1ed80 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
1ed90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1eda0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
1edb0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
1edc0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1edd0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1ede0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
1edf0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1ee00 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1ee10 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
1ee20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
1ee30 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
1ee40 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
1ee50 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1ee60 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1ee70 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
1ee80 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
1ee90 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
1eea0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
1eeb0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
1eec0 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
1eed0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1eee0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1eef0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1ef00 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
1ef10 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
1ef20 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1ef30 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
1ef40 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1ef50 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
1ef60 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
1ef70 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
1ef80 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
1ef90 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
1efa0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1efb0 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
1efc0 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
1efd0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
1efe0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1eff0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
1f000 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1f010 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
1f020 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1f030 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1f040 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1f050 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1f060 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
1f070 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
1f080 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
1f090 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
1f0a0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
1f0b0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
1f0c0 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
1f0d0 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
1f0e0 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
1f0f0 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
1f100 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1f110 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
1f120 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
1f130 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
1f140 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
1f150 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
1f160 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
1f170 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1f180 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
1f190 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
1f1a0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1f1b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
1f1c0 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
1f1d0 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
1f1e0 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
1f1f0 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
1f200 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
1f210 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
1f220 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
1f230 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
1f240 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
1f250 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
1f260 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1f270 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
1f280 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
1f290 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
1f2a0 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
1f2b0 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
1f2c0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
1f2d0 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
1f2e0 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
1f2f0 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
1f300 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
1f310 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
1f320 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
1f330 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
1f340 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
1f350 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
1f360 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
1f370 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
1f380 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
1f390 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
1f3a0 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
1f3b0 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
1f3c0 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
1f3d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1f3e0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
1f3f0 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
1f400 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
1f410 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
1f420 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
1f430 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
1f440 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
1f450 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
1f460 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
1f470 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
1f480 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1f490 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
1f4a0 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
1f4b0 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
1f4c0 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
1f4d0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1f4e0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
1f4f0 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
1f500 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
1f510 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
1f520 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
1f530 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
1f540 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
1f550 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
1f560 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
1f570 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
1f580 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
1f590 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1f5a0 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
1f5b0 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
1f5c0 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
1f5d0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
1f5e0 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
1f5f0 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
1f600 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
1f610 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
1f620 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
1f630 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
1f640 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
1f650 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
1f660 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
1f670 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
1f680 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
1f690 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
1f6a0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
1f6b0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
1f6c0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
1f6d0 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
1f6e0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
1f6f0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1f700 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1f710 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1f720 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1f730 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
1f740 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1f750 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
1f760 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f770 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1f780 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1f790 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1f7a0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1f7b0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1f7c0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1f7d0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1f7e0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
1f7f0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1f800 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
1f810 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
1f820 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
1f830 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
1f840 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
1f850 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
1f860 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
1f870 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
1f880 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
1f890 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
1f8a0 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
1f8b0 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
1f8c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f8d0 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
1f8e0 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
1f8f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1f900 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
1f910 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1f920 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1f930 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
1f940 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1f950 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1f960 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
1f970 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
1f980 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
1f990 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
1f9a0 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
1f9b0 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
1f9c0 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
1f9d0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
1f9e0 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
1f9f0 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
1fa00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
1fa10 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
1fa20 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1fa30 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
1fa40 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49   change..*/.SQLI
1fa50 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
1fa60 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1fa70 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1fa80 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1fa90 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1faa0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1fab0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1fac0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1fad0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1fae0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1faf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1fb00 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1fb10 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1fb20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1fb30 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1fb40 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
1fb50 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
1fb60 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1fb70 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1fb80 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1fb90 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1fba0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1fbb0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1fbc0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1fbd0 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1fbe0 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1fbf0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1fc00 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1fc10 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1fc20 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1fc30 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1fc40 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
1fc50 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
1fc60 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f  so used as a [co
1fc70 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f  nflict resolutio
1fc80 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72  n mode].** retur
1fc90 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ned from the [sq
1fca0 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f  lite3_vtab_on_co
1fcb0 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66  nflict()] interf
1fcc0 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ace..*/.#define 
1fcd0 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
1fce0 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
1fcf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
1fd00 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
1fd10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
1fd20 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
1fd30 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
1fd40 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
1fd50 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
1fd60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1fd70 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
1fd80 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1fd90 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1fda0 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
1fdb0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
1fdc0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
1fdd0 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
1fde0 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
1fdf0 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
1fe00 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
1fe10 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
1fe20 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
1fe30 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
1fe40 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
1fe50 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1fe60 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
1fe70 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
1fe80 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
1fe90 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
1fea0 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
1feb0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1fec0 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
1fed0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
1fee0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
1fef0 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
1ff00 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
1ff10 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
1ff20 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
1ff30 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
1ff40 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
1ff50 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
1ff60 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1ff70 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
1ff80 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
1ff90 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
1ffa0 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
1ffb0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
1ffc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1ffd0 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
1ffe0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
1fff0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20000 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
20010 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
20020 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
20030 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
20040 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
20050 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
20060 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
20070 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
20080 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
20090 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
200a0 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
200b0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
200c0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
200d0 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
200e0 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
200f0 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
20100 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
20110 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
20120 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
20130 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20140 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20150 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
20160 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
20170 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20180 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
20190 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
201a0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
201b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
201c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
201d0 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
201e0 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
201f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
20200 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20210 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20220 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
20230 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
20240 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
20250 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
20260 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
20270 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
20280 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
20290 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
202a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
202b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
202c0 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
202d0 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
202e0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
202f0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
20300 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
20310 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
20320 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
20330 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
20340 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20350 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
20360 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
20370 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
20380 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
20390 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
203a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
203b0 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
203c0 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
203d0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
203e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
203f0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
20400 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20410 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
20420 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
20430 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20440 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
20450 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
20460 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
20470 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
20480 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20490 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
204a0 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
204b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
204c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
204d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
204e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
204f0 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
20500 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
20510 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
20520 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20530 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
20540 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
20550 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
20560 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20570 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20580 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
20590 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
205a0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
205b0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
205c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
205d0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
205e0 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
205f0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
20600 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20610 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20620 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
20630 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
20640 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
20650 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20660 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20670 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
20680 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
20690 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
206a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
206b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
206c0 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
206d0 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
206e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
206f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20710 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
20720 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
20730 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
20740 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
20750 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
20760 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
20770 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
20780 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
20790 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
207a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
207b0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
207c0 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
207d0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
207e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
207f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
20800 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
20810 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
20820 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
20830 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20840 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
20850 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
20860 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
20870 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
20880 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
20890 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
208a0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
208b0 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
208c0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
208d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
208e0 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
208f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
20900 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
20910 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
20920 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20930 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
20940 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
20950 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
20960 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
20970 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20980 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
20990 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
209a0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
209b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
209c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
209d0 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
209e0 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
209f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20a00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20a10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20a20 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
20a30 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
20a40 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
20a50 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
20a60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20a70 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
20a80 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
20a90 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20aa0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
20ab0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20ac0 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
20ad0 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
20ae0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20af0 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
20b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20b10 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
20b20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
20b30 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
20b40 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
20b50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20b60 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
20b70 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
20b80 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
20b90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20ba0 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20  RECURSIVE       
20bb0 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c       33   /* NUL
20bc0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
20bd0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20be0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20bf0 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
20c00 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
20c10 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
20c20 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  te3.**.** These 
20c30 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
20c40 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
20c50 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
20c60 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
20c70 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
20c80 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
20c90 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
20ca0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
20cb0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
20cc0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
20cd0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
20ce0 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
20cf0 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
20d00 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
20d10 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
20d20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
20d30 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
20d40 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
20d50 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
20d60 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
20d70 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
20d80 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
20d90 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
20da0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
20db0 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
20dc0 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
20dd0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
20de0 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
20df0 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
20e00 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
20e10 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
20e20 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
20e30 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
20e40 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
20e50 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
20e60 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
20e70 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
20e80 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41   The [SQLITE_TRA
20e90 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63  CE_SIZE_LIMIT] c
20ea0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
20eb0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
20ec0 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c  o limit.** the l
20ed0 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20  ength of [bound 
20ee0 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e  parameter] expan
20ef0 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70  sion in the outp
20f00 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72  ut of sqlite3_tr
20f10 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ace()..**.** ^Th
20f20 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
20f30 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
20f40 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
20f50 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
20f60 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
20f70 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
20f80 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
20f90 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
20fa0 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
20fb0 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
20fc0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
20fd0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
20fe0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
20ff0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
21000 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
21010 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
21020 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
21030 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
21040 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
21050 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
21060 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
21070 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
21080 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
21090 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
210a0 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
210b0 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
210c0 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
210d0 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
210e0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
210f0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
21100 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
21110 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
21120 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
21130 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
21140 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
21150 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
21160 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
21170 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
21180 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
21190 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
211a0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
211b0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
211c0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
211d0 4c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  L sqlite3_trace(
211e0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
211f0 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
21200 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
21210 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
21220 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
21230 41 4c 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  AL void *SQLITE_
21240 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
21250 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
21260 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
21270 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
21280 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
21290 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
212a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
212b0 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
212c0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
212d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
212e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
212f0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
21300 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
21310 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
21320 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
21330 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
21340 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
21350 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
21360 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
21370 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
21380 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
21390 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
213a0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
213b0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
213c0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
213d0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
213e0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
213f0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
21400 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
21410 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
21420 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
21430 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
21440 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
21450 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
21460 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
21470 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
21480 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
21490 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69  N is the approxi
214a0 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a  mate number of .
214b0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
214c0 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
214d0 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
214e0 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
214f0 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
21500 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
21510 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e  llback X.  ^If N
21520 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
21530 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  e then the progr
21540 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69  ess.** handler i
21550 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
21560 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
21570 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
21580 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
21590 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
215a0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
215b0 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
215c0 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
215d0 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
215e0 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
215f0 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
21600 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
21610 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
21620 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
21630 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
21640 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
21650 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
21660 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
21670 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
21680 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
21690 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
216a0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
216b0 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
216c0 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
216d0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
216e0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
216f0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
21700 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
21710 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
21720 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
21730 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
21740 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
21750 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
21760 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
21770 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
21780 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21790 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
217a0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
217b0 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
217c0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
217d0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
217e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
217f0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
21800 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
21810 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
21820 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
21830 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
21840 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51  agraph..**.*/.SQ
21850 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
21860 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
21870 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
21880 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
21890 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
218a0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
218b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
218c0 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
218d0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
218e0 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73  * CONSTRUCTOR: s
218f0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
21900 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
21910 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
21920 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
21930 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
21940 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
21950 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
21960 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
21970 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
21980 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
21990 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
219a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
219b0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
219c0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
219d0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
219e0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
219f0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
21a00 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
21a10 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
21a20 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
21a30 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
21a40 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
21a50 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
21a60 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
21a70 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
21a80 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
21a90 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
21aa0 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
21ab0 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
21ac0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
21ad0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
21ae0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
21af0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
21b00 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
21b10 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
21b20 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
21b30 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
21b40 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
21b50 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
21b60 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
21b70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
21b80 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
21b90 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
21ba0 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
21bb0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
21bc0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
21bd0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
21be0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
21bf0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
21c00 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
21c10 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
21c20 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
21c30 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
21c40 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
21c50 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
21c60 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65  encoding will be
21c70 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62   UTF-8 for datab
21c80 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69  ases created usi
21c90 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  ng.** sqlite3_op
21ca0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
21cb0 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65  open_v2().  ^The
21cc0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
21cd0 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a  g for databases.
21ce0 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  ** created using
21cf0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
21d00 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36  ) will be UTF-16
21d10 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
21d20 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
21d30 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
21d40 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
21d50 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
21d60 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
21d70 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
21d80 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
21d90 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
21da0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
21db0 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
21dc0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
21dd0 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
21de0 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
21df0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
21e00 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
21e10 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
21e20 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
21e30 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
21e40 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
21e50 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
21e60 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
21e70 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
21e80 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
21e90 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
21ea0 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
21eb0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
21ec0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
21ed0 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
21ee0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
21ef0 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
21f00 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
21f10 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
21f20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
21f30 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
21f40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
21f50 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
21f60 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
21f70 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
21f80 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
21f90 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
21fa0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
21fb0 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
21fc0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
21fd0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
21fe0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
21ff0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
22000 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
22010 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
22020 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
22030 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
22040 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
22050 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
22060 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
22070 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
22080 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
22090 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
220a0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
220b0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
220c0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
220d0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
220e0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
220f0 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
22100 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
22110 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
22120 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
22130 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
22140 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
22150 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
22160 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
22170 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
22180 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
22190 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
221a0 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
221b0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
221c0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
221d0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
221e0 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
221f0 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
22200 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
22210 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
22220 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
22230 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
22240 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
22250 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
22260 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
22270 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
22280 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
22290 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
222a0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
222b0 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
222c0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
222d0 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
222e0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
222f0 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
22300 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
22310 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
22320 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
22330 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
22340 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
22350 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
22360 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
22370 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
22380 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
22390 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
223a0 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
223b0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
223c0 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
223d0 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
223e0 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
223f0 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
22400 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
22410 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
22420 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
22430 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
22440 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
22450 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
22460 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
22470 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
22480 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
22490 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
224a0 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
224b0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
224c0 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
224d0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
224e0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
224f0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
22500 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
22510 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
22520 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
22530 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
22540 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
22550 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
22560 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
22570 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
22580 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
22590 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
225a0 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
225b0 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
225c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
225d0 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
225e0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
225f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
22600 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
22610 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
22620 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
22630 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
22640 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
22650 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
22660 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
22670 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
22680 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
22690 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
226a0 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
226b0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
226c0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
226d0 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
226e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
226f0 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
22700 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
22710 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
22720 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
22730 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
22740 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
22750 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
22760 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
22770 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
22780 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
22790 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
227a0 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
227b0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
227c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
227d0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
227e0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
227f0 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
22800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22810 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
22820 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
22830 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
22840 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
22850 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
22860 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
22870 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
22880 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
22890 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
228a0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
228b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
228c0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
228d0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
228e0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
228f0 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
22900 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
22910 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
22920 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
22930 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
22940 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
22950 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
22960 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
22970 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
22980 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
22990 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
229a0 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
229b0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
229c0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
229d0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
229e0 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
229f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
22a00 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
22a10 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
22a20 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
22a30 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
22a40 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
22a50 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
22a60 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
22a70 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
22a80 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
22a90 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
22aa0 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
22ab0 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
22ac0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
22ad0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
22ae0 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
22af0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
22b00 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
22b10 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
22b20 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
22b30 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f  ** set in the fo
22b40 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
22b50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22b60 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
22b70 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
22b80 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
22b90 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
22ba0 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
22bb0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
22bc0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
22bd0 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
22be0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
22bf0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
22c00 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51  ion..** As of SQ
22c10 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
22c20 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .7, URI filename
22c30 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
22c40 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a  is turned off.**
22c50 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74   by default, but
22c60 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
22c70 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
22c80 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65   enable URI file
22c90 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  name.** interpre
22ca0 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c  tation by defaul
22cb0 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69  t.  See "[URI fi
22cc0 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64  lenames]" for ad
22cd0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
22ce0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55  rmation..**.** U
22cf0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  RI filenames are
22d00 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e   parsed accordin
22d10 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e  g to RFC 3986. ^
22d20 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61  If the URI conta
22d30 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72  ins an.** author
22d40 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73  ity, then it mus
22d50 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65  t be either an e
22d60 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74  mpty string or t
22d70 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c  he string .** "l
22d80 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74  ocalhost". ^If t
22d90 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20  he authority is 
22da0 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72  not an empty str
22db0 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73  ing or "localhos
22dc0 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72  t", an .** error
22dd0 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20   is returned to 
22de0 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65  the caller. ^The
22df0 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e   fragment compon
22e00 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66  ent of a URI, if
22e10 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73   .** present, is
22e20 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
22e30 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
22e40 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20   path component 
22e50 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68  of the URI as th
22e60 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69  e name of the di
22e70 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68  sk file.** which
22e80 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
22e90 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20  tabase. ^If the 
22ea0 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68  path begins with
22eb0 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72   a '/' character
22ec0 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  , .** then it is
22ed0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
22ee0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
22ef0 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64  . ^If the path d
22f00 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a  oes not begin .*
22f10 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65  * with a '/' (me
22f20 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61  aning that the a
22f30 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e  uthority section
22f40 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
22f50 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65   the URI).** the
22f60 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e  n the path is in
22f70 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72  terpreted as a r
22f80 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a  elative path. .*
22f90 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20  * ^(On windows, 
22fa0 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e  the first compon
22fb0 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75  ent of an absolu
22fc0 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61  te path .** is a
22fd0 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61   drive specifica
22fe0 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29  tion (e.g. "C:")
22ff0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  .)^.**.** [[core
23000 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
23010 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
23020 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
23030 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
23040 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
23050 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
23060 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
23070 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
23080 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
23090 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
230a0 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
230b0 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69  Lite and its bui
230c0 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e  lt-in [VFSes] in
230d0 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66  terpret the.** f
230e0 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70  ollowing query p
230f0 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
23100 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
23110 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
23120 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
23130 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
23140 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
23150 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
23160 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
23170 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
23180 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
23190 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
231a0 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
231b0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
231c0 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
231d0 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
231e0 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
231f0 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
23200 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
23210 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
23220 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
23230 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
23240 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
23250 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
23260 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
23270 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
23280 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
23290 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
232a0 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
232b0 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
232c0 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
232d0 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
232e0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
232f0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
23300 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
23310 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
23320 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
23330 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
23340 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
23350 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
23360 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
23370 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
23380 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
23390 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
233a0 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
233b0 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
233c0 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
233d0 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
233e0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
233f0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
23400 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
23410 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
23420 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
23430 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
23440 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
23450 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
23460 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
23470 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
23480 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  n_v2(). ^If the 
23490 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
234a0 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
234b0 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
234c0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
234d0 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
234e0 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
234f0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
23500 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
23510 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
23520 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
23530 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
23540 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
23550 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
23560 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
23570 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
23580 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
23590 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
235a0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
235b0 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
235c0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
235d0 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
235e0 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
235f0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
23600 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
23610 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
23620 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
23630 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
23640 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
23650 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
23660 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
23670 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
23680 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
23690 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
236a0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
236b0 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
236c0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
236d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
236e0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
236f0 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
23700 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
23710 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
23720 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
23730 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
23740 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
23750 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
23760 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
23770 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
23780 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
23790 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
237a0 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
237b0 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
237c0 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
237d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
237e0 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
237f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
23800 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
23810 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
23820 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
23830 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
23840 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
23850 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
23860 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
23870 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
23880 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
23890 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
238a0 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
238b0 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
238c0 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
238d0 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
238e0 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
238f0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
23900 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
23910 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
23920 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c  E flag..**.**  <
23930 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a  li> <b>psow</b>:
23940 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d   ^The psow param
23950 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77  eter indicates w
23960 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
23970 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73  e.**     [powers
23980 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70  afe overwrite] p
23990 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20  roperty does or 
239a0 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74  does not apply t
239b0 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f  o the.**     sto
239c0 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68  rage media on wh
239d0 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ich the database
239e0 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a   file resides..*
239f0 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f  *.**  <li> <b>no
23a00 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e  lock</b>: ^The n
23a10 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20  olock parameter 
23a20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
23a30 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  ry parameter.** 
23a40 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74      which if set
23a50 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c   disables file l
23a60 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61  ocking in rollba
23a70 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73  ck journal modes
23a80 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69  .  This.**     i
23a90 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63  s useful for acc
23aa0 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73  essing a databas
23ab0 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65  e on a filesyste
23ac0 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a  m that does not.
23ad0 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c  **     support l
23ae0 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e  ocking.  Caution
23af0 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72  :  Database corr
23b00 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73  uption might res
23b10 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20  ult if two.**   
23b20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73    or more proces
23b30 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65  ses write to the
23b40 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61   same database a
23b50 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68  nd any one of th
23b60 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65  ose.**     proce
23b70 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b  sses uses nolock
23b80 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  =1..**.**  <li> 
23b90 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e  <b>immutable</b>
23ba0 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65  : ^The immutable
23bb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
23bc0 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a  boolean query.**
23bd0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74       parameter t
23be0 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68  hat indicates th
23bf0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
23c00 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f  file is stored o
23c10 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e  n.**     read-on
23c20 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e  ly media.  ^When
23c30 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65   immutable is se
23c40 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  t, SQLite assume
23c50 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20  s that the.**   
23c60 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20    database file 
23c70 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
23c80 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f  d, even by a pro
23c90 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72  cess with higher
23ca0 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67  .**     privileg
23cb0 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61  e, and so the da
23cc0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
23cd0 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61   read-only and a
23ce0 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20  ll locking.**   
23cf0 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74    and change det
23d00 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c  ection is disabl
23d10 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65  ed.  Caution: Se
23d20 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61  tting the immuta
23d30 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65  ble.**     prope
23d40 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73  rty on a databas
23d50 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73  e file that does
23d60 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20   in fact change 
23d70 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20  can result.**   
23d80 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71    in incorrect q
23d90 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64  uery results and
23da0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  /or [SQLITE_CORR
23db0 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20  UPT] errors..** 
23dc0 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53      See also: [S
23dd0 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
23de0 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20  TABLE]..**      
23df0 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a   .** </ul>.**.**
23e00 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
23e10 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65  unknown paramete
23e20 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63  r in the query c
23e30 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
23e40 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65  I is not an.** e
23e50 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65  rror.  Future ve
23e60 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
23e70 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e   might understan
23e80 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65  d additional que
23e90 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ry.** parameters
23ea0 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70  .  See "[query p
23eb0 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73  arameters with s
23ec0 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74  pecial meaning t
23ed0 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a  o SQLite]" for.*
23ee0 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
23ef0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
23f00 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  [[URI filename e
23f10 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52  xamples]] <h3>UR
23f20 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
23f30 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c  les</h3>.**.** <
23f40 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
23f50 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65   align=center ce
23f60 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20  llpadding=5>.** 
23f70 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c  <tr><th> URI fil
23f80 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75  enames <th> Resu
23f90 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  lts.** <tr><td> 
23fa0 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64  file:data.db <td
23fb0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
23fc0 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
23fd0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
23fe0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e  rrent directory.
23ff0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
24000 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
24010 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20  a.db<br>.**     
24020 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d       file:///hom
24030 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
24040 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  br> .**         
24050 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73   file://localhos
24060 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  t/home/fred/data
24070 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a  .db <br> <td> .*
24080 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
24090 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
240a0 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
240b0 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  ta.db"..** <tr><
240c0 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73  td> file://darks
240d0 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  tar/home/fred/da
240e0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
240f0 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
24100 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20  . "darkstar" is 
24110 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64  not a recognized
24120 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c   authority..** <
24130 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68  tr><td style="wh
24140 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70  ite-space:nowrap
24150 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  "> .**          
24160 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d  file:///C:/Docum
24170 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74  ents%20and%20Set
24180 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74  tings/fred/Deskt
24190 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20  op/data.db.**   
241a0 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f    <td> Windows o
241b0 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69  nly: Open the fi
241c0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20  le "data.db" on 
241d0 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f  fred's desktop o
241e0 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20  n drive.**      
241f0 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61      C:. Note tha
24200 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69  t the %20 escapi
24210 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70  ng in this examp
24220 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74  le is not strict
24230 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ly .**          
24240 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63  necessary - spac
24250 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e  e characters can
24260 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c   be used literal
24270 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ly.**          i
24280 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e  n URI filenames.
24290 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
242a0 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
242b0 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20  o&cache=private 
242c0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
242d0 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74    Open file "dat
242e0 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
242f0 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66  rent directory f
24300 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63  or read-only acc
24310 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ess..**         
24320 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   Regardless of w
24330 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
24340 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20  ared-cache mode 
24350 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a  is enabled by.**
24360 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c            defaul
24370 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65  t, use a private
24380 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c   cache..** <tr><
24390 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
243a0 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d  red/data.db?vfs=
243b0 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64  unix-dotfile <td
243c0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
243d0 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
243e0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
243f0 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
24400 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22  S "unix-dotfile"
24410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
24420 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73  t uses dot-files
24430 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73   in place of pos
24440 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b  ix advisory lock
24450 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ing..** <tr><td>
24460 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
24470 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e  de=readonly <td>
24480 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
24490 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c   error. "readonl
244a0 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69  y" is not a vali
244b0 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65  d option for the
244c0 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65   "mode" paramete
244d0 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  r..** </table>.*
244e0 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65  *.** ^URI hexade
244f0 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
24500 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65  uences (%HH) are
24510 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69   supported withi
24520 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a  n the path and.*
24530 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  * query componen
24540 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68  ts of a URI. A h
24550 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
24560 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69  e sequence consi
24570 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63  sts of a.** perc
24580 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d  ent sign - "%" -
24590 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61   followed by exa
245a0 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63  ctly two hexadec
245b0 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20  imal digits .** 
245c0 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63  specifying an oc
245d0 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f  tet value. ^Befo
245e0 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71  re the path or q
245f0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
24600 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65  of a.** URI file
24610 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72  name are interpr
24620 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65  eted, they are e
24630 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
24640 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68  -8 and all .** h
24650 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
24660 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c  e sequences repl
24670 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  aced by a single
24680 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67   byte containing
24690 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   the.** correspo
246a0 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20  nding octet. If 
246b0 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e  this process gen
246c0 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69  erates an invali
246d0 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  d UTF-8 encoding
246e0 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73  ,.** the results
246f0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
24700 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
24710 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
24720 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
24730 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
24740 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
24750 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
24760 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
24770 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
24780 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
24790 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
247a0 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
247b0 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
247c0 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
247d0 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
247e0 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
247f0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
24800 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
24810 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
24820 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
24830 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
24840 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
24850 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
24860 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73  ws Runtime users
24870 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f  :</b>  The tempo
24880 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d  rary directory m
24890 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72  ust be set.** pr
248a0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73  ior to calling s
248b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
248c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
248d0 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  ().  Otherwise, 
248e0 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75  various.** featu
248f0 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65  res that require
24900 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70   the use of temp
24910 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20  orary files may 
24920 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  fail..**.** See 
24930 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74  also: [sqlite3_t
24940 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a  emp_directory].*
24950 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
24960 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
24970 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
24980 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
24990 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
249a0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
249b0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
249c0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
249d0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
249e0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
249f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
24a00 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
24a10 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
24a20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
24a30 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
24a40 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
24a50 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
24a60 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
24a70 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
24a80 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
24a90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
24aa0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
24ab0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24ac0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
24ad0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
24ae0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
24af0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
24b00 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
24b10 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
24b20 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
24b30 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
24b40 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
24b50 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
24b60 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
24b70 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
24b80 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
24b90 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
24ba0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
24bb0 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
24bc0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
24bd0 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
24be0 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
24bf0 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
24c00 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
24c10 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
24c20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
24c30 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
24c40 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
24c50 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
24c60 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
24c70 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
24c80 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
24c90 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
24ca0 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
24cb0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
24cc0 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
24cd0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
24ce0 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
24cf0 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
24d00 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
24d10 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
24d20 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
24d30 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
24d40 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
24d50 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
24d60 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
24d70 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
24d80 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
24d90 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
24da0 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
24db0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
24dc0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
24dd0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
24de0 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
24df0 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
24e00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
24e10 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
24e20 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
24e30 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
24e40 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
24e50 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
24e60 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
24e70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
24e80 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
24e90 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
24ea0 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
24eb0 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
24ec0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
24ed0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24ee0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
24ef0 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
24f00 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
24f10 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
24f20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
24f30 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
24f40 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
24f50 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
24f60 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
24f70 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
24f80 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
24f90 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
24fa0 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
24fb0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
24fc0 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
24fd0 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
24fe0 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
24ff0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
25000 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
25010 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
25020 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
25030 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
25040 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
25050 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
25060 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
25070 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
25080 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
25090 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
250a0 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
250b0 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
250c0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
250d0 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
250e0 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
250f0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
25100 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
25110 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
25120 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
25130 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
25140 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
25150 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
25160 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
25170 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
25180 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
25190 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
251a0 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
251b0 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
251c0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
251d0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
251e0 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
251f0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
25200 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
25210 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
25220 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
25230 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
25240 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
25250 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
25260 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
25270 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
25280 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
25290 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
252a0 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
252b0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
252c0 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
252d0 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
252e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
252f0 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
25300 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
25310 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
25320 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
25330 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
25340 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
25350 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
25360 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
25370 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
25380 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
25390 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51  desirable..*/.SQ
253a0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
253b0 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
253c0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  ALL sqlite3_uri_
253d0 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
253e0 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
253f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
25400 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ram);.SQLITE_API
25410 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
25420 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  ALL sqlite3_uri_
25430 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68  boolean(const ch
25440 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74  ar *zFile, const
25450 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69   char *zParam, i
25460 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 51  nt bDefault);.SQ
25470 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
25480 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54  _int64 SQLITE_ST
25490 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72  DCALL sqlite3_ur
254a0 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
254b0 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
254c0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
254d0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
254e0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
254f0 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20  And Messages.** 
25500 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
25510 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
25520 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65  st recent sqlite
25530 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73  3_* API call ass
25540 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
25550 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
25560 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c  ction] D failed,
25570 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
25580 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74  3_errcode(D) int
25590 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
255a0 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
255b0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
255c0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
255d0 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a  code] for that.*
255e0 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49  * API call..** I
255f0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
25600 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73  t API call was s
25610 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68  uccessful,.** th
25620 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
25630 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
25640 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
25650 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  defined..** ^The
25660 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
25670 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
25680 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
25690 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
256a0 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
256b0 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
256c0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
256d0 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
256e0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
256f0 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
25700 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
25710 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
25720 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
25730 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
25740 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
25750 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
25760 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
25770 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
25780 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
25790 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
257a0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
257b0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
257c0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
257d0 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
257e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
257f0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
25800 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
25810 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
25820 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
25830 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
25840 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
25850 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
25860 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
25870 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
25880 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
25890 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
258a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
258b0 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72  3_errstr() inter
258c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
258d0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
258e0 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64  e text.** that d
258f0 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65  escribes the [re
25900 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55  sult code], as U
25910 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  TF-8..** ^(Memor
25920 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
25930 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
25940 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
25950 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20  ternally.** and 
25960 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65  must not be free
25970 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
25980 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68  tion)^..**.** Wh
25990 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
259a0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
259b0 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
259c0 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
259d0 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
259e0 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
259f0 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
25a00 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
25a10 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
25a20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
25a30 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
25a40 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
25a50 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
25a60 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
25a70 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
25a80 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
25a90 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
25aa0 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
25ab0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
25ac0 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
25ad0 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
25ae0 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
25af0 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
25b00 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
25b10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
25b20 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
25b30 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
25b40 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
25b50 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
25b60 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
25b70 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
25b80 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
25b90 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
25ba0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
25bb0 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
25bc0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
25bd0 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
25be0 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
25bf0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
25c00 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
25c10 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
25c20 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
25c30 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
25c40 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
25c50 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
25c60 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
25c70 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
25c80 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
25c90 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
25ca0 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
25cb0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
25cc0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
25cd0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
25ce0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53  (sqlite3 *db);.S
25cf0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
25d00 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
25d10 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
25d20 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
25d30 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  b);.SQLITE_API c
25d40 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54  onst char *SQLIT
25d50 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
25d60 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
25d70 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
25d80 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
25d90 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
25da0 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
25db0 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  e3*);.SQLITE_API
25dc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
25dd0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
25de0 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
25df0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25e00 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  : Prepared State
25e10 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
25e20 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
25e30 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
25e40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25e50 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
25e60 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
25e70 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
25e80 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
25e90 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68  tement that.** h
25ea0 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64  as been compiled
25eb0 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72   into binary for
25ec0 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74  m and is ready t
25ed0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a  o be evaluated..
25ee0 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65  **.** Think of e
25ef0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
25f00 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20  t as a separate 
25f10 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d  computer program
25f20 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  .  The.** origin
25f30 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73  al SQL text is s
25f40 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70  ource code.  A p
25f50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25f60 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20  t object .** is 
25f70 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a  the compiled obj
25f80 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53  ect code.  All S
25f90 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  QL must be conve
25fa0 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70  rted into a.** p
25fb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25fc0 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20  t before it can 
25fd0 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  be run..**.** Th
25fe0 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20  e life-cycle of 
25ff0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
26000 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61  ment object usua
26010 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68  lly goes like th
26020 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
26030 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
26040 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
26050 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e  ment object usin
26060 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
26070 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69  re_v2()]..** <li
26080 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
26090 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73   [parameters] us
260a0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
260b0 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
260c0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
260d0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
260e0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
260f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
26100 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
26110 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
26120 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
26130 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
26140 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
26150 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
26160 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
26170 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
26180 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
26190 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
261a0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
261b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
261c0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70  .** </ol>.*/.typ
261d0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
261e0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
261f0 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
26200 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
26210 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f   Limits.** METHO
26220 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
26230 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
26240 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
26250 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
26260 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
26270 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
26280 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
26290 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
262a0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
262b0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
262c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
262d0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
262e0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
262f0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
26300 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
26310 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
26320 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
26330 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
26340 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
26350 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
26360 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
26370 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
26380 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
26390 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
263a0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
263b0 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
263c0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
263d0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
263e0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
263f0 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
26400 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
26410 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
26420 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
26430 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
26440 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
26450 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
26460 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
26470 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
26480 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
26490 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
264a0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
264b0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
264c0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
264d0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
264e0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
264f0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
26500 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
26510 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
26520 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
26530 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
26540 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
26550 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
26560 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
26570 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
26580 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
26590 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
265a0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
265b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
265c0 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
265d0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
265e0 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
265f0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
26600 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
26610 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
26620 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
26630 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
26640 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
26650 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
26660 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
26670 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
26680 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
26690 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
266a0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
266b0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
266c0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
266d0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
266e0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
266f0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
26700 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
26710 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
26720 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
26730 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
26740 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
26750 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
26760 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
26770 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
26780 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
26790 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
267a0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
267b0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
267c0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
267d0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
267e0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
267f0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
26800 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
26810 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
26820 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
26830 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
26840 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
26850 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
26860 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
26870 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
26880 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
26890 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
268a0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
268b0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
268c0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
268d0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
268e0 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
268f0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
26900 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
26910 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
26920 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
26930 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
26940 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
26950 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
26960 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
26970 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
26980 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
26990 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
269a0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
269b0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
269c0 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ses..*/.SQLITE_A
269d0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
269e0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69  DCALL sqlite3_li
269f0 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
26a00 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
26a10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26a20 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
26a30 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
26a40 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
26a50 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
26a60 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
26a70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
26a80 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
26a90 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
26aa0 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
26ab0 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
26ac0 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
26ad0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
26ae0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
26af0 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
26b00 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
26b10 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
26b20 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
26b30 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
26b40 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
26b50 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
26b60 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
26b70 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
26b80 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
26b90 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
26ba0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
26bb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26bc0 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
26bd0 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
26be0 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
26bf0 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
26c00 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26c10 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
26c20 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
26c30 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
26c40 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
26c50 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
26c60 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
26c70 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
26c80 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
26c90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
26ca0 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
26cb0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
26cc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26cd0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
26ce0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
26cf0 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
26d00 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
26d10 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
26d20 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
26d30 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
26d40 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
26d50 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
26d60 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
26d70 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
26d80 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26d90 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
26da0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
26db0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
26dc0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
26dd0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
26de0 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
26df0 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
26e00 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
26e10 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26e20 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
26e30 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
26e40 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
26e50 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
26e60 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
26e70 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
26e80 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
26e90 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
26ea0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
26eb0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
26ec0 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
26ed0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
26ee0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26ef0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
26f00 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
26f10 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
26f20 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
26f30 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
26f40 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
26f50 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73  .  This limit is
26f60 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a   not currently.*
26f70 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75  * enforced, thou
26f80 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  gh that might be
26f90 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66   added in some f
26fa0 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
26fb0 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  .** SQLite.</dd>
26fc0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
26fd0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
26fe0 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  _ARG]] ^(<dt>SQL
26ff0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
27000 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
27010 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
27020 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
27030 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
27040 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
27050 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  [SQLITE_LIMIT_AT
27060 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53  TACHED]] ^(<dt>S
27070 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
27080 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
27090 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
270a0 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
270b0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
270c0 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
270d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
270e0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
270f0 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  ENGTH]].** ^(<dt
27100 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
27110 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
27120 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
27130 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
27140 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
27150 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
27160 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
27170 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
27180 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
27190 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
271a0 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20  BLE_NUMBER]].** 
271b0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
271c0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
271d0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
271e0 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
271f0 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
27200 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
27210 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
27220 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
27230 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
27240 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
27250 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
27260 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
27270 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
27280 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
27290 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
272a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
272b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
272c0 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28  KER_THREADS]] ^(
272d0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
272e0 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c  _WORKER_THREADS<
272f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27300 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
27310 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b  f auxiliary work
27320 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20  er threads that 
27330 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65  a single.** [pre
27340 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27350 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e   may start.</dd>
27360 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  )^.** </dl>.*/.#
27370 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
27380 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  MIT_LENGTH      
27390 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a                0.
273a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
273b0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20  IMIT_SQL_LENGTH 
273c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
273d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
273e0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20  LIMIT_COLUMN    
273f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27400 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
27410 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
27420 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
27430 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
27440 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
27450 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
27460 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
27470 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
27480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27490 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
274a0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
274b0 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20  ON_ARG          
274c0 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
274d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
274e0 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  HED             
274f0 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
27500 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
27510 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20  _PATTERN_LENGTH 
27520 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
27530 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
27540 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20  IABLE_NUMBER    
27550 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
27560 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52   SQLITE_LIMIT_TR
27570 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20  IGGER_DEPTH     
27580 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
27590 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  e SQLITE_LIMIT_W
275a0 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20  ORKER_THREADS   
275b0 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a          11../*.*
275c0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
275d0 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
275e0 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
275f0 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
27600 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20  nt compiler}.** 
27610 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
27620 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
27630 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
27640 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
27650 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
27660 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
27670 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
27680 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
27690 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
276a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
276b0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
276c0 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
276d0 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
276e0 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
276f0 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
27700 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
27710 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
27720 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
27730 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a  _open_v2()] or.*
27740 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
27750 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62  6()].  The datab
27760 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
27770 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
27780 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  n closed..**.** 
27790 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
277a0 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
277b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
277c0 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
277d0 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
277e0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
277f0 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
27800 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
27810 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
27820 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
27830 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
27840 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27850 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
27860 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
27870 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
27880 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79  *.** ^If the nBy
27890 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e  te argument is n
278a0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53  egative, then zS
278b0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
278c0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
278d0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
278e0 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69  If nByte is posi
278f0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
27900 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
27910 66 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f  f bytes read fro
27920 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79  m zSql.  ^If nBy
27930 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  te is zero, then
27940 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20   no prepared.** 
27950 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e  statement is gen
27960 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68  erated..** If th
27970 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74  e caller knows t
27980 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
27990 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
279a0 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a  erminated, then.
279b0 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  ** there is a sm
279c0 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  all performance 
279d0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73  advantage to pas
279e0 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
279f0 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
27a00 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
27a10 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
27a20 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
27a30 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
27a40 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
27a50 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  r..**.** ^If pzT
27a60 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
27a70 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
27a80 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
27a90 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
27aa0 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
27ab0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
27ac0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
27ad0 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
27ae0 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
27af0 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
27b00 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
27b10 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
27b20 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
27b30 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
27b40 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
27b50 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
27b60 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
27b70 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
27b80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
27b90 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
27ba0 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
27bb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
27bc0 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
27bd0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
27be0 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
27bf0 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
27c00 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
27c10 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
27c20 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
27c30 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
27c40 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
27c50 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
27c60 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
27c70 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
27c80 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
27c90 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
27ca0 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
27cb0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
27cc0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
27cd0 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
27ce0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
27cf0 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
27d00 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
27d10 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
27d20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
27d30 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
27d40 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
27d50 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
27d60 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
27d70 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
27d80 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
27d90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27da0 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
27db0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
27dc0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
27dd0 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
27de0 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
27df0 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
27e00 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
27e10 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
27e20 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
27e30 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
27e40 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
27e50 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
27e60 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
27e70 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
27e80 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
27e90 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
27ea0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
27eb0 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
27ec0 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
27ed0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
27ee0 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
27ef0 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
27f00 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
27f10 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
27f20 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
27f30 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
27f40 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
27f50 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
27f60 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
27f70 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
27f80 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
27f90 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
27fa0 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
27fb0 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
27fc0 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
27fd0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
27fe0 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
27ff0 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
28000 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
28010 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49  As many as [SQLI
28020 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45  TE_MAX_SCHEMA_RE
28030 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20  TRY].** retries 
28040 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72  will occur befor
28050 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
28060 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65   gives up and re
28070 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a  turns an error..
28080 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
28090 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
280a0 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
280b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
280c0 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
280d0 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
280e0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
280f0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
28100 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
28110 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
28120 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
28130 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
28140 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
28150 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
28160 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
28170 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
28180 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
28190 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
281a0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
281b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
281c0 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
281d0 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
281e0 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
281f0 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
28200 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
28210 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
28220 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
28230 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
28240 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
28250 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
28260 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
28270 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
28280 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
28290 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
282a0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
282b0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
282c0 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
282d0 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
282e0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
282f0 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
28300 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
28310 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
28320 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
28330 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
28340 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
28350 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
28360 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
28370 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
28380 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
28390 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
283a0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
283b0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
283c0 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
283d0 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
283e0 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
283f0 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
28400 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
28410 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
28420 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
28430 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
28440 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
28450 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
28460 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
28470 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
28480 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
28490 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
284a0 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
284b0 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
284c0 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
284d0 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70  ABLE_STAT3] comp
284e0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
284f0 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c  is enabled..** <
28500 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  /li>.** </ol>.*/
28510 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
28520 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
28530 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
28540 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
28550 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
28560 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
28570 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
28580 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
28590 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
285a0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
285b0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
285c0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
285d0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
285e0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
285f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
28600 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
28610 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
28620 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
28630 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
28640 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
28650 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
28660 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
28670 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
28680 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
28690 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
286a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
286b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
286c0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
286d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
286e0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
286f0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
28700 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
28710 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
28720 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
28730 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
28740 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
28750 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
28760 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
28770 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
28780 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
28790 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
287a0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
287b0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
287c0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
287d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
287e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
287f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
28800 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
28810 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
28820 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
28830 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
28840 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
28850 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
28860 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
28870 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
28880 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
28890 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
288a0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
288b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
288c0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
288d0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
288e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
288f0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
28900 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
28910 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
28920 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
28930 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
28940 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
28950 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
28960 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
28970 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
28980 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
28990 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
289a0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
289b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
289c0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
289d0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
289e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
289f0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
28a00 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
28a10 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
28a20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
28a30 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
28a40 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
28a50 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
28a60 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
28a70 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
28a80 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
28a90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28aa0 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
28ab0 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45  tement SQL.** ME
28ac0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
28ad0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  mt.**.** ^This i
28ae0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
28af0 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
28b00 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
28b10 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
28b20 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
28b30 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
28b40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28b50 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  if that statemen
28b60 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  t was.** compile
28b70 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
28b80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28b90 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
28ba0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
28bb0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
28bc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
28bd0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
28be0 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
28bf0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
28c00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
28c10 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
28c20 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
28c30 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
28c40 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
28c50 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
28c60 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
28c70 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
28c80 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
28c90 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
28ca0 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
28cb0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
28cc0 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
28cd0 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
28ce0 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
28cf0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
28d00 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
28d10 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
28d20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28d30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
28d40 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
28d50 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
28d60 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
28d70 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
28d80 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
28d90 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
28da0 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
28db0 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
28dc0 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
28dd0 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
28de0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
28df0 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
28e00 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
28e10 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
28e20 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
28e30 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
28e40 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
28e50 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
28e60 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
28e70 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
28e80 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
28e90 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
28ea0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
28eb0 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
28ec0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
28ed0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
28ee0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
28ef0 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
28f00 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
28f10 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
28f20 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
28f30 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
28f40 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
28f50 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
28f60 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
28f70 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
28f80 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
28f90 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
28fa0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
28fb0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
28fc0 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
28fd0 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
28fe0 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
28ff0 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
29000 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
29010 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
29020 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
29030 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
29040 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
29050 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
29060 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
29070 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
29080 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
29090 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
290a0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
290b0 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
290c0 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
290d0 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
290e0 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
290f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
29100 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
29110 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
29120 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
29130 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
29140 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
29150 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
29160 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  sk..*/.SQLITE_AP
29170 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
29180 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d  CALL sqlite3_stm
29190 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
291a0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
291b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
291c0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
291d0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
291e0 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
291f0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
29200 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
29210 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
29220 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
29230 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
29240 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
29250 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
29260 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
29270 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
29280 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
29290 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
292a0 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
292b0 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20   neither run to 
292c0 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75  completion (retu
292d0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
292e0 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69  DONE] from [sqli
292f0 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f  te3_step(S)]) no
29300 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20  r.** been reset 
29310 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
29320 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
29330 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
29340 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
29350 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
29360 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
29370 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
29380 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
29390 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
293a0 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
293b0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
293c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
293d0 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
293e0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
293f0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
29400 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
29410 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
29420 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
29430 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
29440 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
29450 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
29460 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
29470 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
29480 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
29490 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
294a0 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
294b0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
294c0 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
294d0 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
294e0 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
294f0 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
29500 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
29510 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
29520 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
29530 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
29540 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53  ction open..*/.S
29550 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
29560 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
29570 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
29580 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
29590 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
295a0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
295b0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
295c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
295d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
295e0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
295f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29600 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
29610 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
29620 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
29630 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
29640 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
29650 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
29660 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
29670 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
29680 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
29690 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
296a0 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
296b0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
296c0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
296d0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
296e0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
296f0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
29700 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
29710 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
29720 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29730 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
29740 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
29750 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
29760 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
29770 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
29780 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
29790 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
297a0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
297b0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
297c0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
297d0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
297e0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
297f0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
29800 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
29810 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
29820 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
29830 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
29840 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
29850 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
29860 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  lue.  The.** [sq
29870 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
29880 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  )] interface can
29890 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73   be used to cons
298a0 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20  truct a new .** 
298b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
298c0 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20  3_value from an 
298d0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
298e0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
298f0 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
29900 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
29910 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
29920 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
29930 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
29940 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
29950 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
29960 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
29970 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
29980 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
29990 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
299a0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
299b0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
299c0 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
299d0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
299e0 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
299f0 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
29a00 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
29a10 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
29a20 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
29a30 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
29a40 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
29a50 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
29a60 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
29a70 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
29a80 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
29a90 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
29aa0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
29ab0 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
29ac0 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
29ad0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
29ae0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
29af0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
29b00 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29b10 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
29b20 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
29b30 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
29b40 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
29b50 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
29b60 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
29b70 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
29b80 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
29b90 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
29ba0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
29bb0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
29bc0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
29bd0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
29be0 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
29bf0 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
29c00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29c10 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
29c20 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
29c30 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
29c40 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
29c50 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
29c60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
29c70 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
29c80 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
29c90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29ca0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
29cb0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
29cc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
29cd0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
29ce0 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
29cf0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29d00 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
29d10 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
29d20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
29d30 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
29d40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
29d50 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
29d60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
29d70 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
29d80 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
29d90 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
29da0 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
29db0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29dc0 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
29dd0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
29de0 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
29df0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e00 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
29e10 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
29e20 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
29e30 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
29e40 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
29e50 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
29e60 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
29e70 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
29e80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
29e90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
29ea0 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
29eb0 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
29ec0 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
29ed0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
29ee0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
29ef0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
29f00 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
29f10 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
29f20 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
29f30 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
29f40 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
29f50 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
29f60 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
29f70 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
29f80 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
29f90 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
29fa0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
29fb0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
29fc0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
29fd0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
29fe0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
29ff0 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
2a000 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
2a010 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2a020 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
2a030 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
2a040 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
2a050 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
2a060 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
2a070 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
2a080 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
2a090 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
2a0a0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
2a0b0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2a0c0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2a0d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
2a0e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
2a0f0 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
2a100 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ng}.** METHOD: s
2a110 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2a120 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
2a130 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
2a140 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
2a150 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2a160 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
2a170 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
2a180 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
2a190 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
2a1a0 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
2a1b0 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
2a1c0 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
2a1d0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
2a1e0 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
2a1f0 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
2a200 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
2a210 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
2a220 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
2a230 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
2a240 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
2a250 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
2a260 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
2a270 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
2a280 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
2a290 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
2a2a0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
2a2b0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
2a2c0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
2a2d0 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
2a2e0 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
2a2f0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
2a300 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
2a310 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2a320 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
2a330 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2a340 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2a350 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2a360 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
2a370 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
2a380 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
2a390 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
2a3a0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
2a3b0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2a3c0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
2a3d0 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
2a3e0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
2a3f0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2a400 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
2a410 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
2a420 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
2a430 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
2a440 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2a450 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
2a460 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
2a470 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
2a480 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
2a490 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
2a4a0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
2a4b0 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
2a4c0 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
2a4d0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
2a4e0 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
2a4f0 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
2a500 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
2a510 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
2a520 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
2a530 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2a540 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
2a550 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
2a560 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
2a570 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
2a580 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
2a590 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
2a5a0 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
2a5b0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
2a5c0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
2a5d0 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
2a5e0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2a5f0 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
2a600 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
2a610 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
2a620 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2a630 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
2a640 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2a650 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
2a660 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2a670 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a680 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
2a690 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
2a6a0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2a6b0 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c  blob() is a NULL
2a6c0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
2a6d0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2a6e0 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64  er.** is ignored
2a6f0 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73   and the end res
2a700 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20  ult is the same 
2a710 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  as sqlite3_bind_
2a720 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  null()..**.** ^(
2a730 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
2a740 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
2a750 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
2a760 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
2a770 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
2a780 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
2a790 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
2a7a0 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
2a7b0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2a7c0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
2a7d0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
2a7e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2a7f0 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
2a800 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2a810 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2a820 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2a830 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2a840 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
2a850 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
2a860 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
2a870 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
2a880 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2a890 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2a8a0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2a8b0 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
2a8c0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2a8d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2a8e0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
2a8f0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
2a900 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2a910 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
2a920 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
2a930 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
2a940 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
2a950 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
2a960 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2a970 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74  ext16() or sqlit
2a980 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2a990 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61   then.** that pa
2a9a0 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
2a9b0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a  the byte offset.
2a9c0 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ** where the NUL
2a9d0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
2a9e0 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67  d occur assuming
2a9f0 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65   the string were
2aa00 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74   NUL.** terminat
2aa10 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
2aa20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
2aa30 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73   at byte offsets
2aa40 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74   less than .** t
2aa50 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2aa60 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2aa70 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2aa80 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65  ing string value
2aa90 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e   will.** contain
2aaa0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20   embedded NULs. 
2aab0 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65   The result of e
2aac0 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c  xpressions invol
2aad0 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ving strings.** 
2aae0 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
2aaf0 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
2ab00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
2ab10 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
2ab20 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e  e BLOB and strin
2ab30 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66  g binding interf
2ab40 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73  aces.** is a des
2ab50 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
2ab60 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2ab70 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
2ab80 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
2ab90 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2aba0 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
2abb0 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
2abc0 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
2abd0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
2abe0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
2abf0 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20  all to bind API 
2ac00 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  fails..** ^If th
2ac10 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2ac20 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
2ac30 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
2ac40 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
2ac50 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
2ac60 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
2ac70 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
2ac80 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
2ac90 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
2aca0 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
2acb0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
2acc0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
2acd0 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
2ace0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
2acf0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
2ad00 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
2ad10 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2ad20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
2ad30 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
2ad40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2ad50 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2ad60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ..**.** ^The six
2ad70 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2ad80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2ad90 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  64() must be one
2ada0 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   of.** [SQLITE_U
2adb0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
2adc0 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  F16], [SQLITE_UT
2add0 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49  F16BE], or [SQLI
2ade0 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74  TE_UTF16LE].** t
2adf0 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e  o specify the en
2ae00 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65  coding of the te
2ae10 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  xt in the third 
2ae20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a  parameter.  If.*
2ae30 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75  * the sixth argu
2ae40 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2ae50 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73  bind_text64() is
2ae60 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
2ae70 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65  ** allowed value
2ae80 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f  s shown above, o
2ae90 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e  r if the text en
2aea0 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2aeb0 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ent.** from the 
2aec0 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
2aed0 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20  ed by the sixth 
2aee0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
2aef0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2af00 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2af10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2af20 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
2af30 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
2af40 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
2af50 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
2af60 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
2af70 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
2af80 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
2af90 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
2afa0 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
2afb0 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
2afc0 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
2afd0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
2afe0 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
2aff0 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
2b000 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
2b010 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
2b020 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
2b030 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
2b040 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2b050 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
2b060 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
2b070 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
2b080 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
2b090 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
2b0a0 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
2b0b0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
2b0c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
2b0d0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
2b0e0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2b0f0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
2b100 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2b110 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
2b120 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
2b130 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
2b140 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
2b150 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
2b160 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
2b170 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
2b180 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
2b190 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
2b1a0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
2b1b0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
2b1c0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
2b1d0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
2b1e0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
2b1f0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
2b200 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b210 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
2b220 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
2b230 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
2b240 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2b250 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
2b260 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
2b270 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
2b280 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2b290 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
2b2a0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
2b2b0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
2b2c0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
2b2d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b2e0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
2b2f0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2b300 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
2b310 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
2b320 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
2b330 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
2b340 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
2b350 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2b360 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
2b370 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
2b380 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
2b390 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
2b3a0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
2b3b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2b3c0 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
2b3d0 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
2b3e0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
2b3f0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
2b400 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2b410 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
2b420 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
2b430 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
2b440 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
2b450 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
2b460 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2b470 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2b480 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
2b490 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2b4a0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2b4b0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
2b4c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2b4d0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2b4e0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2b4f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2b500 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
2b510 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2b520 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
2b530 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
2b540 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
2b550 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2b560 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  L sqlite3_bind_b
2b570 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
2b580 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2b590 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
2b5a0 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
2b5b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2b5c0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2b5d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2b5e0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2b5f0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
2b600 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2b610 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53   int, double);.S
2b620 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2b630 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2b640 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
2b650 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b660 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
2b670 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2b680 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2b690 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
2b6a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
2b6b0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c  ite3_int64);.SQL
2b6c0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2b6d0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2b6e0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
2b6f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2b700 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2b710 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2b720 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2b730 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2b740 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
2b750 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2b760 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
2b770 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2b780 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2b790 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2b7a0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2b7b0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2b7c0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
2b7d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2b7e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2b7f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2b800 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b810 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
2b820 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2b830 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2b840 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2b850 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e  )(void*), unsign
2b860 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67  ed char encoding
2b870 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2b880 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2b890 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
2b8a0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2b8b0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
2b8c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
2b8d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2b8e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2b8f0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2b900 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2b910 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 53  , int, int n);.S
2b920 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2b930 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2b940 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2b950 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
2b960 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
2b970 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  _uint64);../*.**
2b980 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2b990 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
2b9a0 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ers.** METHOD: s
2b9b0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2b9c0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
2b9d0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
2b9e0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
2b9f0 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
2ba00 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
2ba10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2ba20 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
2ba30 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
2ba40 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
2ba50 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
2ba60 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
2ba70 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
2ba80 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
2ba90 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
2baa0 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
2bab0 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
2bac0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
2bad0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
2bae0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
2baf0 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
2bb00 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
2bb10 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
2bb20 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
2bb30 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
2bb40 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
2bb50 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
2bb60 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
2bb70 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
2bb80 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
2bb90 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
2bba0 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
2bbb0 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
2bbc0 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
2bbd0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
2bbe0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
2bbf0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2bc00 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2bc10 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2bc20 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2bc30 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
2bc40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2bc50 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2bc60 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2bc70 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2bc80 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2bc90 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2bca0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2bcb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2bcc0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
2bcd0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st Parameter.** 
2bce0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2bcf0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2bd00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2bd10 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
2bd20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2bd30 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
2bd40 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
2bd50 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
2bd60 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2bd70 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
2bd80 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
2bd90 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
2bda0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2bdb0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2bdc0 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
2bdd0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
2bde0 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
2bdf0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2be00 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
2be10 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
2be20 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
2be30 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
2be40 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
2be50 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
2be60 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
2be70 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
2be80 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2be90 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
2bea0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
2beb0 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
2bec0 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
2bed0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
2bee0 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
2bef0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
2bf00 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
2bf10 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
2bf20 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
2bf30 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
2bf40 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
2bf50 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
2bf60 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
2bf70 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
2bf80 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
2bf90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
2bfa0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2bfb0 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
2bfc0 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
2bfd0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
2bfe0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
2bff0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
2c000 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
2c010 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
2c020 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
2c030 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2c040 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2c050 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2c060 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2c070 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2c080 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2c090 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2c0a0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2c0b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2c0c0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2c0d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2c0e0 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
2c0f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2c100 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2c110 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2c120 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
2c130 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
2c140 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
2c150 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
2c160 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
2c170 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2c180 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
2c190 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
2c1a0 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
2c1b0 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
2c1c0 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
2c1d0 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
2c1e0 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
2c1f0 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
2c200 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
2c210 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2c220 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
2c230 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
2c240 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
2c250 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
2c260 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
2c270 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
2c280 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
2c290 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
2c2a0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
2c2b0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
2c2c0 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
2c2d0 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
2c2e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2c2f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
2c300 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2c310 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2c320 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2c330 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2c340 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
2c350 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2c360 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2c370 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2c380 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2c390 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2c3a0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2c3b0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
2c3c0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
2c3d0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
2c3e0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
2c3f0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
2c400 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2c410 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2c420 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2c430 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
2c440 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
2c450 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
2c460 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
2c470 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
2c480 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2c490 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
2c4a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c4b0 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
2c4c0 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
2c4d0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
2c4e0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
2c4f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2c500 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2c510 4c 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  L sqlite3_clear_
2c520 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
2c530 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2c540 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2c550 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
2c560 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d   Result Set.** M
2c570 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2c580 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  tmt.**.** ^Retur
2c590 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
2c5a0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2c5b0 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
2c5c0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
2c5d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c5e0 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
2c5f0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
2c600 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
2c610 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
2c620 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
2c630 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
2c640 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
2c650 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2c660 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
2c670 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
2c680 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2c690 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2c6a0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
2c6b0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2c6c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c6d0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
2c6e0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2c6f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2c700 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2c710 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2c720 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
2c730 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
2c740 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
2c750 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
2c760 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2c770 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
2c780 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2c790 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
2c7a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2c7b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2c7c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2c7d0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
2c7e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c7f0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
2c800 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2c810 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
2c820 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
2c830 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
2c840 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2c850 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c860 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
2c870 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
2c880 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
2c890 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2c8a0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
2c8b0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
2c8c0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2c8d0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
2c8e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
2c8f0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
2c900 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
2c910 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
2c920 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c930 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
2c940 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
2c950 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2c960 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2c970 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2c980 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2c990 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2c9a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2c9b0 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2c9c0 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2c9d0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
2c9e0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2c9f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2ca00 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2ca10 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
2ca20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
2ca30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
2ca40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
2ca50 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
2ca60 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
2ca70 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
2ca80 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
2ca90 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
2caa0 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
2cab0 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
2cac0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2cad0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2cae0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
2caf0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
2cb00 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
2cb10 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
2cb20 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
2cb30 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
2cb40 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
2cb50 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
2cb60 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
2cb70 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
2cb80 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
2cb90 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
2cba0 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
2cbb0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
2cbc0 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51   the next..*/.SQ
2cbd0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2cbe0 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
2cbf0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2cc00 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
2cc10 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53  stmt*, int N);.S
2cc20 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2cc30 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
2cc40 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
2cc50 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
2cc60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2cc70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cc80 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
2cc90 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
2cca0 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
2ccb0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2ccc0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2ccd0 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
2cce0 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
2ccf0 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
2cd00 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
2cd10 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
2cd20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
2cd30 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
2cd40 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
2cd50 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2cd60 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
2cd70 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2cd80 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
2cd90 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
2cda0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
2cdb0 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
2cdc0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2cdd0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
2cde0 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
2cdf0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
2ce00 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
2ce10 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2ce20 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
2ce30 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
2ce40 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2ce50 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
2ce60 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2ce70 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
2ce80 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
2ce90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2cea0 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
2ceb0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2cec0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2ced0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2cee0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2cef0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2cf00 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2cf10 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2cf20 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2cf30 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2cf40 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
2cf50 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
2cf60 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
2cf70 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
2cf80 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
2cf90 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
2cfa0 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
2cfb0 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
2cfc0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
2cfd0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
2cfe0 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
2cff0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2d000 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2d010 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
2d020 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2d030 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
2d040 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
2d050 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2d060 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
2d070 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
2d080 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
2d090 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
2d0a0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
2d0b0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
2d0c0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
2d0d0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
2d0e0 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
2d0f0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
2d100 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
2d110 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2d120 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2d130 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
2d140 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
2d150 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
2d160 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
2d170 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
2d180 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
2d190 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
2d1a0 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
2d1b0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
2d1c0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2d1d0 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
2d1e0 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
2d1f0 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
2d200 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
2d210 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
2d220 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
2d230 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
2d240 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
2d250 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
2d260 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
2d270 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
2d280 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
2d290 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
2d2a0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
2d2b0 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
2d2c0 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
2d2d0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
2d2e0 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
2d2f0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
2d300 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
2d310 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
2d320 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
2d330 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
2d340 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
2d350 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
2d360 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
2d370 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
2d380 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2d390 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2d3a0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2d3b0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
2d3c0 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
2d3d0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
2d3e0 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
2d3f0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2d400 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
2d410 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
2d420 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2d430 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2d440 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
2d450 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2d460 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
2d470 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
2d480 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
2d490 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
2d4a0 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
2d4b0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
2d4c0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2d4d0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2d4e0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2d4f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2d500 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54  onst char *SQLIT
2d510 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2d520 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2d530 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2d540 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2d550 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2d560 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2d570 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d580 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
2d590 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2d5a0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2d5b0 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54  onst char *SQLIT
2d5c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2d5d0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2d5e0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2d5f0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2d600 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
2d610 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2d620 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2d630 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
2d640 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2d650 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2d660 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
2d670 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2d680 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
2d690 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2d6a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2d6b0 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  nst void *SQLITE
2d6c0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d6d0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2d6e0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2d6f0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2d700 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
2d710 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
2d720 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2d730 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2d740 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  3_stmt.**.** ^(T
2d750 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2d760 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
2d770 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2d780 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
2d790 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
2d7a0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2d7b0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2d7c0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
2d7d0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
2d7e0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
2d7f0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
2d800 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
2d810 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2d820 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
2d830 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
2d840 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
2d850 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
2d860 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2d870 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2d880 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
2d890 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2d8a0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
2d8b0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2d8c0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
2d8d0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2d8e0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
2d8f0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
2d900 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
2d910 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2d920 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
2d930 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
2d940 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
2d950 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
2d960 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
2d970 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
2d980 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
2d990 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
2d9a0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
2d9b0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
2d9c0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
2d9d0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
2d9e0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
2d9f0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
2da00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
2da10 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
2da20 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
2da30 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2da40 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
2da50 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
2da60 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
2da70 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
2da80 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
2da90 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
2daa0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
2dab0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
2dac0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
2dad0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
2dae0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
2daf0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
2db00 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
2db10 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
2db20 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
2db30 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
2db40 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
2db50 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
2db60 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
2db70 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
2db80 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
2db90 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
2dba0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2dbb0 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  st char *SQLITE_
2dbc0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2dbd0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
2dbe0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2dbf0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2dc00 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
2dc10 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2dc20 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2dc30 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2dc40 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2dc50 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
2dc60 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
2dc70 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
2dc80 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2dc90 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
2dca0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
2dcb0 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
2dcc0 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
2dcd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2dce0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2dcf0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2dd00 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
2dd10 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2dd20 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
2dd30 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
2dd40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2dd50 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
2dd60 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
2dd70 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
2dd80 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
2dd90 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
2dda0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
2ddb0 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
2ddc0 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
2ddd0 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
2dde0 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
2ddf0 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
2de00 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
2de10 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
2de20 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
2de30 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
2de40 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2de50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2de60 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
2de70 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
2de80 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
2de90 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2dea0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2deb0 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
2dec0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
2ded0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2dee0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
2def0 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
2df00 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
2df10 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
2df20 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
2df30 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
2df40 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
2df50 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2df60 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
2df70 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
2df80 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
2df90 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
2dfa0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
2dfb0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
2dfc0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2dfd0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
2dfe0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
2dff0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
2e000 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
2e010 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
2e020 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
2e030 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
2e040 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
2e050 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
2e060 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
2e070 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
2e080 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
2e090 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2e0a0 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
2e0b0 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
2e0c0 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
2e0d0 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
2e0e0 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
2e0f0 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
2e100 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
2e110 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
2e120 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
2e130 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
2e140 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
2e150 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
2e160 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
2e170 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
2e180 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
2e190 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
2e1a0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2e1b0 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
2e1c0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
2e1d0 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
2e1e0 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
2e1f0 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
2e200 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
2e210 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
2e220 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2e230 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2e240 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
2e250 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2e260 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
2e270 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2e280 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
2e290 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
2e2a0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
2e2b0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2e2c0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
2e2d0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2e2e0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
2e2f0 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
2e300 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
2e310 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
2e320 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
2e330 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
2e340 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
2e350 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
2e360 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
2e370 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
2e380 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
2e390 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2e3a0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
2e3b0 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
2e3c0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
2e3d0 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
2e3e0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
2e3f0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
2e400 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
2e410 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
2e420 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
2e430 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
2e440 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
2e450 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2e460 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2e470 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
2e480 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
2e490 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
2e4a0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
2e4b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
2e4c0 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
2e4d0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2e4e0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
2e4f0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2e500 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
2e510 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
2e520 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
2e530 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
2e540 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
2e550 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
2e560 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
2e570 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2e580 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
2e590 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e5a0 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
2e5b0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
2e5c0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
2e5d0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2e5e0 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
2e5f0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
2e600 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
2e610 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
2e620 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
2e630 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
2e640 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
2e650 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
2e660 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
2e670 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2e680 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2e690 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
2e6a0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
2e6b0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
2e6c0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
2e6d0 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
2e6e0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
2e6f0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
2e700 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
2e710 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
2e720 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
2e730 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2e740 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
2e750 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
2e760 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
2e770 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
2e780 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
2e790 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
2e7a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
2e7b0 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
2e7c0 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
2e7d0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2e7e0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
2e7f0 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
2e800 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
2e810 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
2e820 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
2e830 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
2e840 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
2e850 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
2e860 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2e870 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
2e880 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2e890 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2e8a0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
2e8b0 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
2e8c0 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
2e8d0 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
2e8e0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
2e8f0 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
2e900 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
2e910 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
2e920 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
2e930 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2e940 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
2e950 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
2e960 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
2e970 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
2e980 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
2e990 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
2e9a0 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
2e9b0 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
2e9c0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
2e9d0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
2e9e0 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
2e9f0 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
2ea00 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
2ea10 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
2ea20 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
2ea30 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
2ea40 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2ea50 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
2ea60 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
2ea70 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2ea80 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
2ea90 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
2eaa0 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
2eab0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2eac0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2ead0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
2eae0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
2eaf0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
2eb00 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2eb10 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
2eb20 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
2eb30 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2eb40 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
2eb50 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
2eb60 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
2eb70 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2eb80 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2eb90 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2eba0 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
2ebb0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2ebc0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
2ebd0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
2ebe0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
2ebf0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
2ec00 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
2ec10 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
2ec20 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
2ec30 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
2ec40 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
2ec50 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
2ec60 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
2ec70 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
2ec80 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2ec90 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2eca0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ecb0 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
2ecc0 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
2ecd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ece0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2ecf0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
2ed00 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
2ed10 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
2ed20 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2ed30 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
2ed40 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
2ed50 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
2ed60 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
2ed70 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
2ed80 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
2ed90 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2eda0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2edb0 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
2edc0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2edd0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2ede0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2edf0 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
2ee00 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2ee10 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2ee20 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2ee30 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
2ee40 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2ee50 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2ee60 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
2ee70 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2ee80 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
2ee90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2eea0 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
2eeb0 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
2eec0 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
2eed0 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
2eee0 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
2eef0 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
2ef00 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
2ef10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
2ef20 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
2ef30 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
2ef40 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2ef50 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
2ef60 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2ef70 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
2ef80 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
2ef90 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
2efa0 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
2efb0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2efc0 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
2efd0 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
2efe0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
2eff0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2f000 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
2f010 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
2f020 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2f030 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
2f040 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
2f050 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
2f060 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2f070 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
2f080 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
2f090 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
2f0a0 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
2f0b0 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
2f0c0 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
2f0d0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
2f0e0 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
2f0f0 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
2f100 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
2f110 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
2f120 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
2f130 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2f140 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2f150 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54  ount()].*/.SQLIT
2f160 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2f170 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2f180 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
2f190 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2f1a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f1b0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
2f1c0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
2f1d0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
2f1e0 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
2f1f0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
2f200 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
2f210 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
2f220 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
2f230 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
2f240 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2f250 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
2f260 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
2f270 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
2f280 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
2f290 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
2f2a0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
2f2b0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2f2c0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
2f2d0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
2f2e0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
2f2f0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
2f300 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
2f310 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
2f320 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2f330 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
2f340 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
2f350 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
2f360 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
2f370 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
2f380 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
2f390 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
2f3a0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
2f3b0 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
2f3c0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
2f3d0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2f3e0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
2f3f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2f400 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
2f410 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2f420 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2f430 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
2f440 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2f450 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
2f460 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
2f470 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
2f480 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
2f490 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
2f4a0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
2f4b0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
2f4c0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
2f4d0 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
2f4e0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2f4f0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
2f500 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2f510 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2f520 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
2f530 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2f540 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
2f550 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
2f560 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
2f570 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
2f580 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
2f590 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
2f5a0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
2f5b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2f5c0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
2f5d0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
2f5e0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2f5f0 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
2f600 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
2f610 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2f620 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2f630 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
2f640 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
2f650 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2f660 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
2f670 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
2f680 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
2f690 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
2f6a0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2f6b0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2f6c0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
2f6d0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
2f6e0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2f6f0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2f700 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
2f710 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
2f720 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2f730 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
2f740 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2f750 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
2f760 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
2f770 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
2f780 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
2f790 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
2f7a0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
2f7b0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2f7c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2f7d0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
2f7e0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
2f7f0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
2f800 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2f810 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2f820 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
2f830 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
2f840 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
2f850 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2f860 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
2f870 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
2f880 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
2f890 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2f8a0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
2f8b0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
2f8c0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2f8d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2f8e0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
2f8f0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2f900 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
2f910 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
2f920 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
2f930 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2f940 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
2f950 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f960 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2f970 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2f980 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
2f990 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
2f9a0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
2f9b0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
2f9c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2f9d0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
2f9e0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2f9f0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2fa00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2fa10 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2fa20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2fa30 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
2fa40 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
2fa50 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
2fa60 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
2fa70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
2fa80 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
2fa90 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
2faa0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2fab0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
2fac0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
2fad0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
2fae0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
2faf0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
2fb00 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
2fb10 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2fb20 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2fb30 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
2fb40 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
2fb50 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
2fb60 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
2fb70 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
2fb80 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
2fb90 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
2fba0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
2fbb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fbc0 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
2fbd0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
2fbe0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2fbf0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
2fc00 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
2fc10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2fc20 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
2fc30 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2fc40 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
2fc50 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2fc60 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
2fc70 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2fc80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2fc90 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2fca0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2fcb0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2fcc0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2fcd0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2fce0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
2fcf0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2fd00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2fd10 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
2fd20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2fd30 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
2fd40 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2fd50 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2fd60 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2fd70 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2fd80 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2fd90 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
2fda0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2fdb0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2fdc0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2fdd0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
2fde0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2fdf0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2fe00 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2fe10 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2fe20 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
2fe30 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2fe40 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
2fe50 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
2fe60 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2fe70 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
2fe80 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2fe90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fea0 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
2feb0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2fec0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2fed0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2fee0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2fef0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2ff00 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
2ff10 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2ff20 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
2ff30 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2ff40 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
2ff50 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2ff60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2ff70 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2ff80 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2ff90 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2ffa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ffb0 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
2ffc0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2ffd0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2ffe0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2fff0 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
30000 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
30010 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
30020 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
30030 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
30040 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
30050 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30060 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
30070 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
30080 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
30090 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
300a0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
300b0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
300c0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
300d0 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
300e0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
300f0 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
30100 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
30110 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
30120 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
30130 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
30140 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
30150 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
30160 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
30170 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
30180 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
30190 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
301a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
301b0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
301c0 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
301d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
301e0 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
301f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30200 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
30210 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
30220 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
30230 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
30240 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
30250 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
30260 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
30270 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
30280 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
30290 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57  nter..**.** <b>W
302a0 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65  arning:</b> ^The
302b0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
302c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
302d0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
302e0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
302f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30300 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20  ] object.  In a 
30310 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e  multithreaded en
30320 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e  vironment,.** an
30330 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
30340 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
30350 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  t may only be us
30360 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a  ed safely with.*
30370 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
30380 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
30390 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
303a0 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
303b0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
303c0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
303d0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
303e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
303f0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
30400 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
30410 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
30420 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
30430 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
30440 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
30450 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30460 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
30470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
30480 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61  tes()], the beha
30490 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65  vior is not thre
304a0 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  adsafe..**.** Th
304b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
304c0 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
304d0 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
304e0 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
304f0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
30500 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
30510 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
30520 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
30530 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
30540 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
30550 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
30560 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
30570 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
30580 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
30590 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
305a0 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
305b0 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
305c0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
305d0 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
305e0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
305f0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
30600 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
30610 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
30620 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
30630 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
30640 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
30650 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
30660 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
30670 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
30680 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
30690 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
306a0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
306b0 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
306c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
306d0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
306e0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
306f0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
30700 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
30710 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
30720 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
30730 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
30740 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
30750 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
30760 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
30770 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
30780 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
30790 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
307a0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
307b0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
307c0 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
307d0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
307e0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
307f0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
30800 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
30810 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
30820 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
30830 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
30840 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
30850 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
30860 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
30870 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
30880 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
30890 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
308a0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
308b0 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  OB    <td> [CAST
308c0 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72  ] to BLOB.** <tr
308d0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
308e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
308f0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
30900 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
30910 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
30920 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
30930 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
30940 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
30950 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
30960 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
30970 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
30980 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
30990 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
309a0 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
309b0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
309c0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
309d0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
309e0 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
309f0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
30a00 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
30a10 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
30a20 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
30a30 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
30a40 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
30a50 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
30a60 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
30a70 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
30a80 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
30a90 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
30aa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
30ab0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
30ac0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
30ad0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
30ae0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
30af0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
30b00 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
30b10 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
30b20 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
30b30 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
30b40 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
30b50 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
30b60 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
30b70 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
30b80 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
30b90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30ba0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
30bb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30bc0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
30bd0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
30be0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
30bf0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
30c00 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
30c10 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
30c20 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
30c30 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
30c40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
30c50 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
30c60 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
30c70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
30c80 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
30c90 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
30ca0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
30cb0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
30cc0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
30cd0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
30ce0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
30cf0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
30d00 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
30d10 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
30d20 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
30d30 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
30d40 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
30d50 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
30d60 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
30d70 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
30d80 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
30d90 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
30da0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
30db0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
30dc0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
30dd0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
30de0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
30df0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
30e00 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
30e10 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
30e20 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
30e30 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
30e40 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
30e50 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
30e60 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
30e70 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
30e80 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
30e90 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
30ea0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
30eb0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
30ec0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
30ed0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
30ee0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
30ef0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
30f00 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
30f10 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
30f20 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
30f30 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
30f40 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
30f50 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
30f60 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
30f70 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
30f80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
30f90 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>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 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
30fc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30fd0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
30fe0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
30ff0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
31000 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
31010 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
31020 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
31030 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
31040 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
31050 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
31060 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
31070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
31080 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
31090 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
310a0 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
310b0 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
310c0 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
310d0 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
310e0 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
310f0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
31100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31110 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
31120 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
31130 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
31140 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
31150 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31160 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
31170 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
31180 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
31190 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
311a0 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
311b0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
311c0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
311d0 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
311e0 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
311f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31200 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
31210 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
31220 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
31230 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
31240 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
31250 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
31260 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
31270 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
31280 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
31290 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
312a0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
312b0 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
312c0 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
312d0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
312e0 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
312f0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
31300 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f  y.  Do <em>not</
31310 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  em> pass the poi
31320 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
31330 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
31340 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
31350 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
31360 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
31370 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
31380 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
31390 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
313a0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
313b0 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
313c0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
313d0 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
313e0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
313f0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
31400 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
31410 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
31420 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
31430 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
31440 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
31450 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
31460 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
31470 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
31480 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
31490 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
314a0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
314b0 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ^.*/.SQLITE_API 
314c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
314d0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
314e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
314f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31500 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
31510 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
31520 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
31530 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
31540 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
31550 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
31560 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
31570 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
31580 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
31590 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
315a0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
315b0 64 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f 53 54  double SQLITE_ST
315c0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
315d0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
315e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
315f0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
31600 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
31610 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
31620 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
31630 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
31640 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
31650 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45  te3_int64 SQLITE
31660 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
31670 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
31680 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31690 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
316a0 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  PI const unsigne
316b0 64 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  d char *SQLITE_S
316c0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
316d0 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
316e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
316f0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
31700 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
31710 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
31720 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
31730 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31740 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
31750 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
31760 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
31770 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
31780 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
31790 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
317a0 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  I sqlite3_value 
317b0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
317c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
317d0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
317e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
317f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31800 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
31810 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
31820 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ect.** DESTRUCTO
31830 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
31840 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31850 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
31860 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
31870 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
31880 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31890 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
318a0 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
318b0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
318c0 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
318d0 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
318e0 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
318f0 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
31900 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
31910 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
31920 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
31930 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
31940 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
31950 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
31960 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
31970 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
31980 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
31990 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
319a0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
319b0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
319c0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
319d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
319e0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
319f0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
31a00 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
31a10 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
31a20 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
31a30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31a40 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
31a50 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
31a60 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
31a70 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
31a80 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
31a90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
31aa0 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
31ab0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
31ac0 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
31ad0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
31ae0 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
31af0 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
31b00 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
31b10 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
31b20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
31b30 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
31b40 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
31b50 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
31b60 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
31b70 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
31b80 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
31b90 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
31ba0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
31bb0 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
31bc0 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
31bd0 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
31be0 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
31bf0 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
31c00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
31c10 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
31c20 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
31c30 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
31c40 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
31c50 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
31c60 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
31c70 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
31c80 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
31c90 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
31ca0 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
31cb0 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
31cc0 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ption..*/.SQLITE
31cd0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
31ce0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
31cf0 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
31d00 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
31d10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31d20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
31d30 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
31d40 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31d50 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31d60 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
31d70 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
31d80 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
31d90 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
31da0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
31db0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
31dc0 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
31dd0 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
31de0 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
31df0 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
31e00 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
31e10 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
31e20 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
31e30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
31e40 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
31e50 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
31e60 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
31e70 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
31e80 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
31e90 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
31ea0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
31eb0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
31ec0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
31ed0 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
31ee0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31ef0 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
31f00 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
31f10 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
31f20 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
31f30 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
31f40 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
31f50 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
31f60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31f70 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
31f80 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
31f90 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
31fa0 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
31fb0 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
31fc0 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
31fd0 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
31fe0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
31ff0 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
32000 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
32010 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
32020 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
32030 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
32040 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
32050 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
32060 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
32070 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
32080 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
32090 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
320a0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
320b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
320c0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
320d0 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
320e0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
320f0 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
32100 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
32110 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
32120 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
32130 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51  tement] S..*/.SQ
32140 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
32150 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
32160 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
32170 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
32180 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32190 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
321a0 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
321b0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
321c0 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
321d0 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
321e0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
321f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
32200 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
32210 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
32220 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
32230 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20  L functions}.** 
32240 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
32250 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
32260 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
32270 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
32280 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
32290 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
322a0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
322b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
322c0 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
322d0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
322e0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
322f0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
32300 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
32310 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
32320 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
32330 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
32340 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
32350 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
32360 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
32370 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
32380 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
32390 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
323a0 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
323b0 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
323c0 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
323d0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
323e0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
323f0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
32400 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
32410 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
32420 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
32430 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
32440 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
32450 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
32460 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
32470 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
32480 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
32490 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
324a0 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
324b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
324c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
324d0 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
324e0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
324f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
32500 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
32510 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
32520 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
32530 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
32540 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
32550 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
32560 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
32570 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
32580 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
32590 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
325a0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
325b0 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
325c0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
325d0 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
325e0 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
325f0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
32600 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
32610 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
32620 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
32630 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
32640 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
32650 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
32660 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
32670 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
32680 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
32690 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
326a0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
326b0 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
326c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
326d0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
326e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
326f0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
32700 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
32710 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
32720 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
32730 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
32740 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
32750 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
32760 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
32770 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
32780 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
32790 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
327a0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
327b0 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
327c0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
327d0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
327e0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
327f0 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
32800 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
32810 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
32820 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
32830 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
32840 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
32850 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
32860 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
32870 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
32880 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
32890 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
328a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
328b0 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73   should set this
328c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
328d0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
328e0 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f  ] if the functio
328f0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
32900 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71   invokes .** [sq
32910 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32920 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16le()] on an in
32930 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  put, or [SQLITE_
32940 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a  UTF16BE] if the.
32950 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
32960 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74  n invokes [sqlit
32970 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
32980 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
32990 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  , or.** [SQLITE_
329a0 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74  UTF16] if [sqlit
329b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
329c0 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b  )] is used, or [
329d0 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20  SQLITE_UTF8].** 
329e0 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65  otherwise.  ^The
329f0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
32a00 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
32a10 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
32a20 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66  mes using.** dif
32a30 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64  ferent preferred
32a40 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c   text encodings,
32a50 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
32a60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
32a70 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f  for.** each enco
32a80 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  ding..** ^When m
32a90 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
32aa0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
32ab0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
32ac0 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
32ad0 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
32ae0 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
32af0 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
32b00 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
32b10 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
32b20 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
32b30 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f  ameter may optio
32b40 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69  nally be ORed wi
32b50 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  th [SQLITE_DETER
32b60 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20  MINISTIC].** to 
32b70 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20  signal that the 
32b80 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c  function will al
32b90 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
32ba0 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65  same result give
32bb0 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e  n.** the same in
32bc0 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69  puts within a si
32bd0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
32be0 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75  nt.  Most SQL fu
32bf0 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64  nctions are.** d
32c00 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
32c10 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e  he built-in [ran
32c20 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74  dom()] SQL funct
32c30 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  ion is an exampl
32c40 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69  e of a.** functi
32c50 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64  on that is not d
32c60 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
32c70 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20  he SQLite query 
32c80 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20  planner is able 
32c90 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64  to.** perform ad
32ca0 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a  ditional optimiz
32cb0 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d  ations on determ
32cc0 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  inistic function
32cd0 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20  s, so use.** of 
32ce0 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  the [SQLITE_DETE
32cf0 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20  RMINISTIC] flag 
32d00 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77  is recommended w
32d10 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  here possible..*
32d20 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
32d30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
32d40 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
32d50 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
32d60 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
32d70 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
32d80 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
32d90 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
32da0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
32db0 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
32dc0 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
32dd0 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
32de0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
32df0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
32e00 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
32e10 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
32e20 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
32e30 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
32e40 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
32e50 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
32e60 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
32e70 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
32e80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
32e90 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
32ea0 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
32eb0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
32ec0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
32ed0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
32ee0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
32ef0 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
32f00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
32f10 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
32f20 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
32f30 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
32f40 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
32f50 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
32f60 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
32f70 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
32f80 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
32f90 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
32fa0 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
32fb0 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
32fc0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
32fd0 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
32fe0 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
32ff0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
33000 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33010 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
33020 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
33030 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
33040 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
33050 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
33060 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
33070 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
33080 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
33090 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
330a0 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
330b0 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
330c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
330d0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
330e0 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
330f0 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
33100 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
33110 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
33120 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
33130 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
33140 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
33150 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
33160 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
33170 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
33180 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
33190 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
331a0 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
331b0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
331c0 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
331d0 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
331e0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
331f0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
33200 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
33210 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
33220 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
33230 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
33240 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
33250 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
33260 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
33270 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
33280 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
33290 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
332a0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
332b0 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
332c0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
332d0 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
332e0 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
332f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
33300 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
33310 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
33320 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
33330 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
33340 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
33350 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
33360 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
33370 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
33380 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
33390 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
333a0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
333b0 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
333c0 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
333d0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
333e0 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
333f0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
33400 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
33410 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
33420 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
33430 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
33440 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
33450 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
33460 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
33470 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
33480 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
33490 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
334a0 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
334b0 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
334c0 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
334d0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
334e0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
334f0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
33500 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
33510 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
33520 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
33530 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
33540 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
33550 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33560 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
33570 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
33580 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
33590 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
335a0 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
335b0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
335c0 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
335d0 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
335e0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
335f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
33600 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
33610 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
33620 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
33630 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
33640 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
33650 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
33660 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
33670 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  L sqlite3_create
33680 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
33690 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
336a0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
336b0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
336c0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
336d0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
336e0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
336f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33700 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
33710 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
33720 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
33730 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
33740 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
33750 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
33760 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33770 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
33780 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
33790 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  LL sqlite3_creat
337a0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
337b0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
337c0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
337d0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
337e0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
337f0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
33800 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
33810 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
33820 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
33830 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
33840 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
33850 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
33860 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
33870 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
33880 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
33890 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
338a0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
338b0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72  DCALL sqlite3_cr
338c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
338d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
338e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
338f0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
33900 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
33910 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
33920 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
33930 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
33940 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
33950 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
33960 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
33970 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33980 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
33990 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
339a0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
339b0 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
339c0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
339d0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
339e0 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
339f0 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
33a00 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
33a10 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
33a20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
33a30 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
33a40 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
33a50 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
33a60 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
33a70 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
33a80 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20     1    /* IMP: 
33a90 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f  R-37514-35566 */
33aa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33ab0 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
33ac0 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33      /* IMP: R-03
33ad0 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65  371-37637 */.#de
33ae0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
33af0 36 42 45 20 20 20 20 20 20 20 20 33 20 20 20 20  6BE        3    
33b00 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d  /* IMP: R-51971-
33b10 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65  34154 */.#define
33b20 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
33b30 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
33b40 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
33b50 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
33b60 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
33b70 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65        5    /* De
33b80 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66  precated */.#def
33b90 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
33ba0 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
33bb0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
33bc0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
33bd0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
33be0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61  EF: Function Fla
33bf0 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
33c00 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
33c10 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69  ORed together wi
33c20 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
33c30 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72  TE_UTF8 | prefer
33c40 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
33c50 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  g] as the fourth
33c60 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
33c70 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33c80 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  function()], [sq
33c90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33ca0 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ction16()], or.*
33cb0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
33cc0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d  e_function_v2()]
33cd0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
33ce0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
33cf0 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a  C    0x800../*.*
33d00 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
33d10 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
33d20 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
33d30 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
33d40 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
33d50 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
33d60 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
33d70 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
33d80 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
33d90 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
33da0 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
33db0 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
33dc0 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
33dd0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
33de0 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
33df0 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
33e00 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
33e10 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67  o encourage prog
33e20 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64  rammers to avoid
33e30 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69  .** these functi
33e40 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74  ons, we will not
33e50 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68   explain what th
33e60 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
33e70 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
33e80 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
33e90 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
33ea0 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45  CATED int SQLITE
33eb0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
33ec0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
33ed0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33ee0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
33ef0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
33f00 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
33f10 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 70 69  ALL sqlite3_expi
33f20 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
33f30 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
33f40 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
33f50 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
33f60 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  ALL sqlite3_tran
33f70 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
33f80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
33f90 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
33fa0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
33fb0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51  EPRECATED int SQ
33fc0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
33fd0 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
33fe0 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
33ff0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
34000 52 45 43 41 54 45 44 20 76 6f 69 64 20 53 51 4c  RECATED void SQL
34010 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
34020 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
34030 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
34040 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
34050 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54  ECATED int SQLIT
34060 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
34070 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
34080 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
34090 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
340a0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
340b0 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c         void*,sql
340c0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
340d0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
340e0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
340f0 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54  QL Values.** MET
34100 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c  HOD: sqlite3_val
34110 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  ue.**.** The C-l
34120 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
34130 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
34140 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
34150 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
34160 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
34170 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
34180 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
34190 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
341a0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
341b0 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a  or aggregate.  .
341c0 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
341d0 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
341e0 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
341f0 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
34200 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
34210 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
34220 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
34230 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
34240 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
34250 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
34260 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
34270 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
34280 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
34290 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20  tes..** The 3rd 
342a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
342b0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
342c0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
342d0 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
342e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
342f0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
34300 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
34310 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34320 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
34330 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
34340 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
34350 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
34360 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
34370 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
34380 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
34390 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
343a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
343b0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
343c0 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
343d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
343e0 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
343f0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
34400 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
34410 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
34420 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
34430 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
34440 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
34450 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
34460 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
34470 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
34480 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
34490 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
344a0 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
344b0 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69  that these routi
344c0 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
344d0 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
344e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
344f0 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
34500 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
34510 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
34520 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
34530 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
34540 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34550 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
34560 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
34570 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
34580 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
34590 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
345a0 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
345b0 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
345c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
345d0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
345e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
345f0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
34600 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
34610 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
34620 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
34630 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
34640 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
34650 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
34660 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
34670 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
34680 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
34690 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
346a0 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
346b0 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
346c0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
346d0 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
346e0 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
346f0 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
34700 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
34710 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
34720 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
34730 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
34740 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
34750 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
34760 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
34770 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
34780 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
34790 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
347a0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
347b0 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
347c0 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
347d0 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
347e0 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
347f0 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
34800 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
34810 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
34820 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
34830 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
34840 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
34850 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
34860 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
34870 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
34880 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
34890 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
348a0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
348b0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
348c0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
348d0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
348e0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
348f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
34900 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
34910 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
34920 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
34930 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
34940 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34950 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
34960 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
34970 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
34980 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
34990 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
349a0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
349b0 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
349c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
349d0 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c  rameters..*/.SQL
349e0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
349f0 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
34a00 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
34a10 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
34a20 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
34a30 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
34a40 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
34a50 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
34a60 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
34a70 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
34a80 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
34a90 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
34aa0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
34ab0 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65  QLITE_API double
34ac0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
34ad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
34ae0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
34af0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
34b00 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
34b10 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
34b20 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
34b30 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
34b40 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
34b50 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
34b60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
34b70 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
34b80 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
34b90 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
34ba0 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
34bb0 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
34bc0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
34bd0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
34be0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
34bf0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
34c00 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
34c10 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
34c20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
34c30 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  nst void *SQLITE
34c40 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
34c50 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
34c60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34c70 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
34c80 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  t void *SQLITE_S
34c90 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
34ca0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
34cb0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
34cc0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
34cd0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
34ce0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
34cf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34d00 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
34d10 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
34d20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
34d30 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
34d40 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
34d50 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
34d60 69 6e 67 20 54 68 65 20 53 75 62 74 79 70 65 20  ing The Subtype 
34d70 4f 66 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a  Of SQL Values.**
34d80 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
34d90 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65  _value.**.** The
34da0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73   sqlite3_value_s
34db0 75 62 74 79 70 65 28 56 29 20 66 75 6e 63 74 69  ubtype(V) functi
34dc0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  on returns the s
34dd0 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20 61 6e  ubtype for.** an
34de0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
34df0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
34e00 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56 2e 20  on] argument V. 
34e10 20 54 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20   The subtype.** 
34e20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61 6e 20  information can 
34e30 62 65 20 75 73 65 64 20 74 6f 20 70 61 73 73 20  be used to pass 
34e40 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75 6e 74  a limited amount
34e50 20 6f 66 20 63 6f 6e 74 65 78 74 20 66 72 6f 6d   of context from
34e60 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75 6e 63  .** one SQL func
34e70 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65 72 2e  tion to another.
34e80 20 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74    Use the [sqlit
34e90 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70  e3_result_subtyp
34ea0 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  e()].** routine 
34eb0 74 6f 20 73 65 74 20 74 68 65 20 73 75 62 74 79  to set the subty
34ec0 70 65 20 66 6f 72 20 74 68 65 20 72 65 74 75 72  pe for the retur
34ed0 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51  n value of an SQ
34ee0 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  L function..**.*
34ef0 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 6e  * SQLite makes n
34f00 6f 20 75 73 65 20 6f 66 20 73 75 62 74 79 70 65  o use of subtype
34f10 20 69 74 73 65 6c 66 2e 20 20 49 74 20 6d 65 72   itself.  It mer
34f20 65 6c 79 20 70 61 73 73 65 73 20 74 68 65 20 73  ely passes the s
34f30 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 74  ubtype.** from t
34f40 68 65 20 72 65 73 75 6c 74 20 6f 66 20 6f 6e 65  he result of one
34f50 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
34f60 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
34f70 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  on] into the.** 
34f80 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68 65 72  input of another
34f90 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
34fa0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 53 51 4c  unsigned int SQL
34fb0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
34fc0 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70  te3_value_subtyp
34fd0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
34fe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34ff0 45 46 3a 20 43 6f 70 79 20 41 6e 64 20 46 72 65  EF: Copy And Fre
35000 65 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20  e SQL Values.** 
35010 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
35020 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  value.**.** ^The
35030 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
35040 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20  up(V) interface 
35050 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
35060 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
35070 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20  ue].** object D 
35080 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
35090 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 63 6f  inter to that co
350a0 70 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  py.  ^The [sqlit
350b0 65 33 5f 76 61 6c 75 65 5d 20 72 65 74 75 72 6e  e3_value] return
350c0 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74  ed.** is a [prot
350d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
350e0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e  lue] object even
350f0 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73   if the input is
35100 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71   not..** ^The sq
35110 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
35120 56 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  V) interface ret
35130 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20 69  urns NULL if V i
35140 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a  s NULL or if a.*
35150 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
35160 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  ion fails..**.**
35170 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
35180 6c 75 65 5f 66 72 65 65 28 56 29 20 69 6e 74 65  lue_free(V) inte
35190 72 66 61 63 65 20 66 72 65 65 73 20 61 6e 20 5b  rface frees an [
351a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
351b0 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75  bject.** previou
351c0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
351d0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
351e0 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66 20 56 20  _dup()].  ^If V 
351f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
35200 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  r.** then sqlite
35210 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20  3_value_free(V) 
35220 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
35230 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  -op..*/.SQLITE_A
35240 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49  PI SQLITE_EXPERI
35250 4d 45 4e 54 41 4c 20 73 71 6c 69 74 65 33 5f 76  MENTAL sqlite3_v
35260 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44  alue *SQLITE_STD
35270 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
35280 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c  ue_dup(const sql
35290 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
352a0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
352b0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
352c0 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
352d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66   sqlite3_value_f
352e0 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ree(sqlite3_valu
352f0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
35300 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
35310 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
35320 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f  Context.** METHO
35330 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
35340 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
35350 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
35360 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
35370 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
35380 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
35390 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
353a0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
353b0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
353c0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
353d0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
353e0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
353f0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
35400 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
35410 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
35420 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
35430 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
35440 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
35450 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
35460 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
35470 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
35480 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
35490 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
354a0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
354b0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
354c0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
354d0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
354e0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
354f0 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
35500 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
35510 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
35520 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35530 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
35540 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
35550 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
35560 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
35570 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
35580 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
35590 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
355a0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
355b0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
355c0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
355d0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
355e0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
355f0 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
35600 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
35610 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
35620 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
35630 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
35640 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
35650 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
35660 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
35670 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
35680 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
35690 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
356a0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
356b0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
356c0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
356d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
356e0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
356f0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
35700 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
35710 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73  er .** when firs
35720 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73  t called if N is
35730 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
35740 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
35750 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  f a memory.** al
35760 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
35770 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
35780 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
35790 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
357a0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
357b0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
357c0 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
357d0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
357e0 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
357f0 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
35800 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
35810 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
35820 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
35830 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
35840 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
35850 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
35860 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
35870 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
35880 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
35890 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
358a0 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20  .)^  Within the 
358b0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c  xFinal callback,
358c0 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79   it is customary
358d0 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69   to set.** N=0 i
358e0 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  n calls to sqlit
358f0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
35900 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61  text(C,N) so tha
35910 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65  t no .** pointle
35920 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ss memory alloca
35930 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a  tions occur..**.
35940 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
35950 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
35960 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
35970 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
35980 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
35990 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
359a0 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
359b0 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
359c0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
359d0 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
359e0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
359f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
35a00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
35a10 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
35a20 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
35a30 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
35a40 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
35a50 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
35a60 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
35a70 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
35a80 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
35a90 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
35aa0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
35ab0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
35ac0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
35ad0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
35ae0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
35af0 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
35b00 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
35b10 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67  DCALL sqlite3_ag
35b20 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
35b30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35b40 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
35b50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35b60 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
35b70 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  nctions.** METHO
35b80 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
35b90 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  xt.**.** ^The sq
35ba0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
35bb0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
35bc0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
35bd0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
35be0 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
35bf0 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
35c00 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
35c10 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
35c20 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
35c30 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
35c40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35c50 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
35c60 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
35c70 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
35c80 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
35c90 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
35ca0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
35cb0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
35cc0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
35cd0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
35ce0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
35cf0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35d00 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
35d10 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
35d20 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  API void *SQLITE
35d30 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
35d40 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
35d50 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
35d60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
35d70 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
35d80 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
35d90 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
35da0 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
35db0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
35dc0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
35dd0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
35de0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
35df0 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
35e00 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
35e10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
35e20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
35e30 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
35e40 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35e50 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
35e60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
35e70 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
35e80 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
35e90 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
35ea0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35eb0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
35ec0 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
35ed0 20 73 71 6c 69 74 65 33 20 2a 53 51 4c 49 54 45   sqlite3 *SQLITE
35ee0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
35ef0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
35f00 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
35f10 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
35f20 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
35f30 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
35f40 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
35f50 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
35f60 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
35f70 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28  may be used by (
35f80 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53  non-aggregate) S
35f90 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
35fa0 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
35fb0 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  adata with argum
35fc0 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
35fd0 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
35fe0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
35ff0 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
36000 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
36010 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
36020 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
36030 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
36040 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
36050 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
36060 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70  etadata may be p
36070 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78  reserved.  An ex
36080 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72  ample.** of wher
36090 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20  e this might be 
360a0 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72  useful is in a r
360b0 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
360c0 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75  n matching.** fu
360d0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
360e0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
360f0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
36100 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74  ession can be st
36110 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64  ored as.** metad
36120 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
36130 69 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20  ith the pattern 
36140 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65  string.  .** The
36150 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  n as long as the
36160 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20   pattern string 
36170 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65  remains the same
36180 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65  ,.** the compile
36190 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
361a0 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
361b0 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
361c0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
361d0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
361e0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
361f0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
36200 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
36210 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
36220 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
36230 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
36240 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
36250 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
36260 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
36270 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
36280 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
36290 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
362a0 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65  unction. ^If the
362b0 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74  re is no metadat
362c0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
362d0 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f  with the functio
362e0 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73  n argument, this
362f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
36300 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
36310 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55  .** returns a NU
36320 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
36330 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
36340 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
36350 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  ,X) interface sa
36360 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74  ves P as metadat
36370 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
36380 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
36390 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
363a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
363b0 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20   ^Subsequent.** 
363c0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
363d0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _get_auxdata(C,N
363e0 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20  ) return P from 
363f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
36400 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
36410 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
36420 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61  call if the meta
36430 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61  data is still va
36440 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69  lid or.** NULL i
36450 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 68  f the metadata h
36460 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 65  as been discarde
36470 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63  d..** ^After eac
36480 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
36490 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
364a0 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 69  N,P,X) where X i
364b0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53  s not NULL,.** S
364c0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
364d0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
364e0 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68   function X with
364f0 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 61   parameter P exa
36500 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68  ctly.** once, wh
36510 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  en the metadata 
36520 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  is discarded..**
36530 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
36540 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 6d  to discard the m
36550 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 74  etadata at any t
36560 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20  ime, including: 
36570 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  <ul>.** <li> whe
36580 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
36590 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
365a0 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20  ameter changes, 
365b0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  or.** <li> when 
365c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
365d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
365e0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
365f0 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  led for the.**  
36600 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e      SQL statemen
36610 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68  t, or.** <li> wh
36620 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  en sqlite3_set_a
36630 75 78 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f  uxdata() is invo
36640 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65  ked again on the
36650 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c   same parameter,
36660 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69   or.** <li> duri
36670 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ng the original 
36680 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
36690 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20  ata() call when 
366a0 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20  a memory .**    
366b0 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72    allocation err
366c0 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e  or occurs. </ul>
366d0 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  )^.**.** Note th
366e0 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e  e last bullet in
366f0 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68   particular.  Th
36700 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 20 69  e destructor X i
36710 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  n .** sqlite3_se
36720 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
36730 58 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  X) might be call
36740 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ed immediately, 
36750 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71  before the.** sq
36760 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
36770 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 76  a() interface ev
36780 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e  en returns.  Hen
36790 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ce sqlite3_set_a
367a0 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75  uxdata().** shou
367b0 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61  ld be called nea
367c0 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  r the end of the
367d0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
367e0 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65  entation and the
367f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  .** function imp
36800 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
36810 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20  ld not make any 
36820 75 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a  use of P after.*
36830 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
36840 78 64 61 74 61 28 29 20 68 61 73 20 62 65 65 6e  xdata() has been
36850 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   called..**.** ^
36860 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
36870 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
36880 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
36890 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
368a0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
368b0 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 63  eters that are c
368c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73  ompile-time cons
368d0 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67  tants, including
368e0 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
368f0 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65  es and [paramete
36900 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69  rs] and expressi
36910 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f  ons composed fro
36920 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a  m the same.)^.**
36930 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
36940 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
36950 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
36960 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
36970 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
36980 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
36990 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
369a0 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
369b0 4c 4c 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  LL sqlite3_get_a
369c0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
369d0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
369e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
369f0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
36a00 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
36a10 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
36a20 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
36a30 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
36a40 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
36a50 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
36a60 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
36a70 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
36a80 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
36a90 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
36aa0 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
36ab0 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
36ac0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
36ad0 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
36ae0 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
36af0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
36b00 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
36b10 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
36b20 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
36b30 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
36b40 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
36b50 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
36b60 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
36b70 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
36b80 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
36b90 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
36ba0 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
36bb0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
36bc0 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
36bd0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
36be0 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
36bf0 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
36c00 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
36c10 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
36c20 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
36c30 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
36c40 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
36c50 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
36c60 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
36c70 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
36c80 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
36c90 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
36ca0 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
36cb0 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  rs..*/.typedef v
36cc0 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
36cd0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
36ce0 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
36cf0 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
36d00 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
36d10 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
36d20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
36d30 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
36d40 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
36d50 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
36d60 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
36d70 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
36d80 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
36d90 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
36da0 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
36db0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
36dc0 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
36dd0 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
36de0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
36df0 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
36e00 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
36e10 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
36e20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36e30 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
36e40 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36e50 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
36e60 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
36e70 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
36e80 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
36e90 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
36ea0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
36eb0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
36ec0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
36ed0 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
36ee0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
36ef0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
36f00 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
36f10 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
36f20 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
36f30 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
36f40 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
36f50 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
36f60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36f70 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
36f80 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
36f90 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
36fa0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
36fb0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
36fc0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
36fd0 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
36fe0 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
36ff0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
37000 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
37010 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
37020 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
37030 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
37040 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
37050 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37060 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 20 61 6e  zeroblob(C,N) an
37070 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37080 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 43 2c 4e 29  _zeroblob64(C,N)
37090 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 73  .** interfaces s
370a0 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
370b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
370c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
370d0 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 42 4c 4f  n to be.** a BLO
370e0 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
370f0 20 7a 65 72 6f 20 62 79 74 65 73 20 61 6e 64 20   zero bytes and 
37100 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2e  N bytes in size.
37110 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37120 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
37130 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
37140 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
37150 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
37160 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37170 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
37180 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
37190 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
371a0 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
371b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
371c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
371d0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
371e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
371f0 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
37200 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
37210 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
37220 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
37230 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
37240 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
37250 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
37260 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
37270 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
37280 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37290 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
372a0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
372b0 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
372c0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
372d0 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
372e0 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
372f0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
37300 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
37310 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
37320 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
37330 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
37340 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
37350 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
37360 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
37370 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
37380 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
37390 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
373a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
373b0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
373c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
373d0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
373e0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
373f0 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
37400 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
37410 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
37420 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
37430 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
37440 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
37450 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
37460 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
37470 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
37480 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37490 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
374a0 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
374b0 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
374c0 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
374d0 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
374e0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
374f0 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
37500 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
37510 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37520 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
37530 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
37540 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
37550 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
37560 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
37570 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
37580 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
37590 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
375a0 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
375b0 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
375c0 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
375d0 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
375e0 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
375f0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
37600 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
37610 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
37620 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
37630 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
37640 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
37650 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
37660 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
37670 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
37680 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
37690 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
376a0 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
376b0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
376c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
376d0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
376e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
376f0 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
37700 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
37710 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
37720 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37730 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
37740 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
37750 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
37760 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
37770 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
37780 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
37790 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
377a0 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
377b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
377c0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
377d0 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
377e0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
377f0 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
37800 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
37810 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
37820 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
37830 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37840 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
37850 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
37860 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
37870 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
37880 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37890 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
378a0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
378b0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
378c0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
378d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
378e0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
378f0 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
37900 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
37910 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
37920 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
37930 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
37940 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
37950 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
37960 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
37970 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
37980 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
37990 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
379a0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
379b0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
379c0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
379d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
379e0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
379f0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
37a00 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37a10 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
37a20 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
37a30 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
37a40 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
37a50 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
37a60 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
37a70 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
37a80 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
37a90 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
37aa0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37ab0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
37ac0 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
37ad0 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
37ae0 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
37af0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
37b00 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
37b10 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
37b20 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
37b30 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
37b40 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  y..** ^The sqlit
37b50 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34  e3_result_text64
37b60 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
37b70 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
37b80 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c  ue of an.** appl
37b90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
37ba0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
37bb0 20 74 65 78 74 20 73 74 72 69 6e 67 20 69 6e 20   text string in 
37bc0 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73  an encoding.** s
37bd0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
37be0 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73 74 29  fifth (and last)
37bf0 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63   parameter, whic
37c00 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a  h must be one.**
37c10 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
37c20 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
37c30 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
37c40 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
37c50 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51  UTF16LE]..** ^SQ
37c60 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
37c70 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
37c80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
37c90 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
37ca0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
37cb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37cc0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
37cd0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
37ce0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
37cf0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37d00 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
37d10 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
37d20 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
37d30 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
37d40 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
37d50 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
37d60 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
37d70 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
37d80 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
37d90 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
37da0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
37db0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
37dc0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
37dd0 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
37de0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
37df0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
37e00 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
37e10 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
37e20 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
37e30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
37e40 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
37e50 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20  ion result.  If 
37e60 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
37e70 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  r is non-negativ
37e80 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75  e, then it.** mu
37e90 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
37ea0 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73  ffset into the s
37eb0 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20  tring where the 
37ec0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
37ed0 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69  ould.** appear i
37ee0 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  f the string whe
37ef0 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65  re NUL terminate
37f00 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
37f10 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a  haracters occur.
37f20 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  ** in the string
37f30 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65   at a byte offse
37f40 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74  t that is less t
37f50 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  han the value of
37f60 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61   the 3rd.** para
37f70 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
37f80 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
37f90 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d   will contain em
37fa0 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20  bedded NULs and 
37fb0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66  the.** result of
37fc0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65   expressions ope
37fd0 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67  rating on string
37fe0 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  s with embedded 
37ff0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
38000 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  d..** ^If the 4t
38010 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
38020 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
38030 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
38040 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
38050 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
38060 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
38070 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
38080 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
38090 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
380a0 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
380b0 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
380c0 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
380d0 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
380e0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
380f0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
38100 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
38110 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
38120 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
38130 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
38140 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
38150 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
38160 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
38170 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
38180 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
38190 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
381a0 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
381b0 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
381c0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
381d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
381e0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
381f0 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
38200 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
38210 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
38220 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
38230 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
38240 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
38250 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
38260 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
38270 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
38280 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
38290 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
382a0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
382b0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
382c0 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
382d0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
382e0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
382f0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
38300 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
38310 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
38320 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
38330 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
38340 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
38350 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
38360 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
38370 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
38380 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
38390 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
383a0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  y of the.** [unp
383b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
383c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
383d0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
383e0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
383f0 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
38400 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
38410 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
38420 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
38430 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
38440 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
38450 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
38460 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
38470 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
38480 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
38490 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
384a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
384b0 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
384c0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20  out harm..** ^A 
384d0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
384e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
384f0 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
38500 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
38510 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
38520 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
38530 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
38540 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
38550 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
38560 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
38570 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
38580 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
38590 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
385a0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
385b0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
385c0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
385d0 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
385e0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
385f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
38600 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
38610 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
38620 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
38630 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
38640 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
38650 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  efined..*/.SQLIT
38660 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
38670 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
38680 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
38690 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
386a0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
386b0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
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 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  _blob64(sqlite3_
38700 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76  context*,const v
38710 6f 69 64 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  oid*,.          
38720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38730 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
38740 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
38750 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
38760 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
38770 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
38780 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
38790 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, do