System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact f387eb7e7f85e11ac64d4217b3b7e271ac447ea7:


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 39 2e 30 22 0a 23 64 65       "3.9.0".#de
10b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
10c0: 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 39 30  ION_NUMBER 30090
10d0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
10e0: 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20  E_SOURCE_ID     
10f0: 20 22 32 30 31 35 2d 31 30 2d 31 34 20 31 32 3a   "2015-10-14 12:
1100: 32 39 3a 35 33 20 61 37 32 31 66 63 30 64 38 39  29:53 a721fc0d89
1110: 34 39 35 35 31 38 66 65 35 36 31 32 65 32 65 33  495518fe5612e2e3
1120: 62 62 63 36 30 62 65 66 64 32 65 39 30 64 22 0a  bbc60befd2e90d".
1130: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1140: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
1150: 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72  y Version Number
1160: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
1170: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20  qlite3_version, 
1180: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
1190: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
11a0: 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20  erfaces provide 
11b0: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
11c0: 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c  tion as the [SQL
11d0: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a  ITE_VERSION],.**
11e0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
11f0: 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53  _NUMBER], and [S
1200: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d  QLITE_SOURCE_ID]
1210: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1220: 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72  macros.** but ar
1230: 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
1240: 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e  h the library in
1250: 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61  stead of the hea
1260: 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75  der file.  ^(Cau
1270: 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d  tious.** program
1280: 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75  mers might inclu
1290: 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74  de assert() stat
12a0: 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20  ements in their 
12b0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a  application to.*
12c0: 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61  * verify that va
12d0: 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
12e0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
12f0: 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72  s match the macr
1300: 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61  os in.** the hea
1310: 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e  der, and thus en
1320: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70  sure that the ap
1330: 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  plication is.** 
1340: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61  compiled with ma
1350: 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61  tching library a
1360: 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e  nd header files.
1370: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1380: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65  te><pre>.** asse
1390: 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  rt( sqlite3_libv
13a0: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d  ersion_number()=
13b0: 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  =SQLITE_VERSION_
13c0: 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73  NUMBER );.** ass
13d0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
13e0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53  te3_sourceid(),S
13f0: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29  QLITE_SOURCE_ID)
1400: 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  ==0 );.** assert
1410: 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33  ( strcmp(sqlite3
1420: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51  _libversion(),SQ
1430: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30  LITE_VERSION)==0
1440: 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   );.** </pre></b
1450: 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
1460: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1470: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1480: 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69   constant contai
1490: 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b  ns the text of [
14a0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a  SQLITE_VERSION].
14b0: 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20  ** macro.  ^The 
14c0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
14d0: 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  on() function re
14e0: 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
14f0: 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65  to the.** to the
1500: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
1510: 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  [] string consta
1520: 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  nt.  The sqlite3
1530: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a  _libversion().**
1540: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f   function is pro
1550: 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  vided for use in
1560: 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20   DLLs since DLL 
1570: 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f  users usually do
1580: 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72   not have.** dir
1590: 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74  ect access to st
15a0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77  ring constants w
15b0: 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20  ithin the DLL.  
15c0: 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
15d0: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
15e0: 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  r() function ret
15f0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
1600: 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c  equal to.** [SQL
1610: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1620: 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ER].  ^The sqlit
1630: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75  e3_sourceid() fu
1640: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a  nction returns .
1650: 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
1660: 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  a string constan
1670: 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73  t whose value is
1680: 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65   the same as the
1690: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55   .** [SQLITE_SOU
16a0: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
16b0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a  cessor macro..**
16c0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
16d0: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d  qlite_version()]
16e0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75   and [sqlite_sou
16f0: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51  rce_id()]..*/.SQ
1700: 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
1710: 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61  EXTERN const cha
1720: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  r sqlite3_versio
1730: 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  n[];.SQLITE_API 
1740: 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
1750: 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1760: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f  e3_libversion(vo
1770: 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
1780: 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
1790: 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
17a0: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
17b0: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
17c0: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
17d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
17e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29  ion_number(void)
17f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1800: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
1810: 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20  ary Compilation 
1820: 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74  Options Diagnost
1830: 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ics.**.** ^The s
1840: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1850: 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63  tion_used() func
1860: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f  tion returns 0 o
1870: 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69  r 1 .** indicati
1880: 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73  ng whether the s
1890: 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20  pecified option 
18a0: 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a  was defined at .
18b0: 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  ** compile time.
18c0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70    ^The SQLITE_ p
18d0: 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69  refix may be omi
18e0: 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a  tted from the .*
18f0: 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61  * option name pa
1900: 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ssed to sqlite3_
1910: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1920: 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54  ed().  .**.** ^T
1930: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
1940: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66  leoption_get() f
1950: 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69  unction allows i
1960: 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72  terating.** over
1970: 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74   the list of opt
1980: 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64  ions that were d
1990: 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c  efined at compil
19a0: 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74  e time by.** ret
19b0: 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20  urning the N-th 
19c0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74  compile time opt
19d0: 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66  ion string.  ^If
19e0: 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
19f0: 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ge,.** sqlite3_c
1a00: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1a10: 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
1a20: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
1a30: 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65   SQLITE_ .** pre
1a40: 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66  fix is omitted f
1a50: 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20  rom any strings 
1a60: 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20  returned by .** 
1a70: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1a80: 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a  ption_get()..**.
1a90: 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20  ** ^Support for 
1aa0: 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66  the diagnostic f
1ab0: 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33  unctions sqlite3
1ac0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
1ad0: 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c  sed().** and sql
1ae0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1af0: 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20  on_get() may be 
1b00: 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69  omitted by speci
1b10: 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53  fying the .** [S
1b20: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49  QLITE_OMIT_COMPI
1b30: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20  LEOPTION_DIAGS] 
1b40: 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c  option at compil
1b50: 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  e time..**.** Se
1b60: 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63  e also: SQL func
1b70: 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f  tions [sqlite_co
1b80: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1b90: 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1ba0: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  te_compileoption
1bb0: 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20  _get()] and the 
1bc0: 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73  [compile_options
1bd0: 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66   pragma]..*/.#if
1be0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
1bf0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1c00: 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20  IAGS.SQLITE_API 
1c10: 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
1c20: 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  LL sqlite3_compi
1c30: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f  leoption_used(co
1c40: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61  nst char *zOptNa
1c50: 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  me);.SQLITE_API 
1c60: 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
1c70: 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1c80: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c90: 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e  _get(int N);.#en
1ca0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
1cb0: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65  REF: Test To See
1cc0: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20   If The Library 
1cd0: 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a  Is Threadsafe.**
1ce0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1cf0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75  _threadsafe() fu
1d00: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a  nction returns z
1d10: 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ero if and only 
1d20: 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73  if.** SQLite was
1d30: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1d40: 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69  utexing code omi
1d50: 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a  tted due to the.
1d60: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
1d70: 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  DSAFE] compile-t
1d80: 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67  ime option being
1d90: 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a   set to 0..**.**
1da0: 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63   SQLite can be c
1db0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20  ompiled with or 
1dc0: 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e  without mutexes.
1dd0: 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53    When.** the [S
1de0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1df0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1e00: 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32   macro is 1 or 2
1e10: 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  , mutexes.** are
1e20: 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c   enabled and SQL
1e30: 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ite is threadsaf
1e40: 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20  e.  When the.** 
1e50: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1e60: 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20  FE] macro is 0, 
1e70: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20  .** the mutexes 
1e80: 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69  are omitted.  Wi
1e90: 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65  thout the mutexe
1ea0: 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66  s, it is not saf
1eb0: 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69  e.** to use SQLi
1ec0: 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20  te concurrently 
1ed0: 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f  from more than o
1ee0: 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a  ne thread..**.**
1ef0: 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65   Enabling mutexe
1f00: 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75  s incurs a measu
1f10: 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63  rable performanc
1f20: 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f  e penalty..** So
1f30: 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20   if speed is of 
1f40: 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63  utmost importanc
1f50: 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73  e, it makes sens
1f60: 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20  e to disable.** 
1f70: 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75  the mutexes.  Bu
1f80: 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61  t for maximum sa
1f90: 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68  fety, mutexes sh
1fa0: 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e  ould be enabled.
1fb0: 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1fc0: 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72   behavior is for
1fd0: 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65   mutexes to be e
1fe0: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  nabled..**.** Th
1ff0: 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
2000: 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61   be used by an a
2010: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61  pplication to ma
2020: 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65  ke sure that the
2030: 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  .** version of S
2040: 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73  QLite that it is
2050: 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74   linking against
2060: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
2070: 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65  th.** the desire
2080: 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65  d setting of the
2090: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
20a0: 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  AFE] macro..**.*
20b0: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
20c0: 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e   only reports on
20d0: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
20e0: 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a  e mutex setting.
20f0: 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ** of the [SQLIT
2100: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c  E_THREADSAFE] fl
2110: 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ag.  If SQLite i
2120: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
2130: 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44  ** SQLITE_THREAD
2140: 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65  SAFE=1 or =2 the
2150: 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e  n mutexes are en
2160: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
2170: 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66   but.** can be f
2180: 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c  ully or partiall
2190: 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67  y disabled using
21a0: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
21b0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a  te3_config()].**
21c0: 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20   with the verbs 
21d0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
21e0: 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53  INGLETHREAD], [S
21f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
2200: 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72  TITHREAD],.** or
2210: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2220: 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28  SERIALIZED].  ^(
2230: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
2240: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
2250: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
2260: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2270: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2280: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2290: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
22a0: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
22b0: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
22c0: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
22d0: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
22e0: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
22f0: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2300: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
2310: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
2320: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
2330: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
2340: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
2350: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
2360: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2370: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2380: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2390: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53  nformation..*/.S
23a0: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
23b0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
23c0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
23d0: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
23e0: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
23f0: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2400: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2410: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2420: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2430: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2440: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2450: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
2460: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
2470: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
2480: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
2490: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
24a0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
24b0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
24c0: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
24d0: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
24e0: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
24f0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2500: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2510: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2520: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2530: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2540: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2550: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
2560: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
2570: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2580: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
2590: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
25a0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
25b0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
25c0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
25d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
25f0: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2600: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2610: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2620: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2630: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2640: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2650: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
2660: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2670: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
2680: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
2690: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
26a0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
26b0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
26c0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
26d0: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
26e0: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
26f0: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2700: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2710: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2720: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2730: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2740: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2750: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
2760: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
2770: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
2780: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2790: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
27a0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
27b0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
27c0: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
27d0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
27e0: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
27f0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2800: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2810: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2820: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2830: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2840: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2850: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
2860: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
2870: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
2880: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
2890: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
28a0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
28b0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
28c0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
28d0: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
28e0: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
28f0: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2900: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2910: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2920: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2930: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2940: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2950: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2960: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2970: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36  gned SQLITE_INT6
2980: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69  4_TYPE sqlite_ui
2990: 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69  nt64;.#elif defi
29a0: 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c  ned(_MSC_VER) ||
29b0: 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41   defined(__BORLA
29c0: 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66  NDC__).  typedef
29d0: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
29e0: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
29f0: 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36   unsigned __int6
2a00: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  4 sqlite_uint64;
2a10: 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66  .#else.  typedef
2a20: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
2a30: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2a40: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2a50: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
2a60: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e  lite_uint64;.#en
2a70: 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69  dif.typedef sqli
2a80: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  te_int64 sqlite3
2a90: 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20  _int64;.typedef 
2aa0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71  sqlite_uint64 sq
2ab0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f  lite3_uint64;../
2ac0: 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e  *.** If compilin
2ad0: 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f  g for a processo
2ae0: 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f  r that lacks flo
2af0: 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70  ating point supp
2b00: 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75  ort,.** substitu
2b10: 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66  te integer for f
2b20: 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a  loating-point..*
2b30: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
2b40: 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f  OMIT_FLOATING_PO
2b50: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75  INT.# define dou
2b60: 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ble sqlite3_int6
2b70: 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  4.#endif../*.** 
2b80: 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e  CAPI3REF: Closin
2b90: 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  g A Database Con
2ba0: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52  nection.** DESTR
2bb0: 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a  UCTOR: sqlite3.*
2bc0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2bd0: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71  3_close() and sq
2be0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2bf0: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
2c00: 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72  structors.** for
2c10: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2c20: 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73  bject..** ^Calls
2c30: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   to sqlite3_clos
2c40: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2c50: 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72  close_v2() retur
2c60: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  n [SQLITE_OK] if
2c70: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2c80: 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63  ] object is succ
2c90: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ca0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2cb0: 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63  iated.** resourc
2cc0: 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74  es are deallocat
2cd0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
2ce0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2cf0: 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61  ction is associa
2d00: 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  ted with unfinal
2d10: 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a  ized prepared.**
2d20: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75   statements or u
2d30: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
2d40: 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73  3_backup objects
2d50: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c   then sqlite3_cl
2d60: 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65  ose().** will le
2d70: 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ave the database
2d80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
2d90: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
2da0: 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49  ITE_BUSY]..** ^I
2db0: 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  f sqlite3_close_
2dc0: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  v2() is called w
2dd0: 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20  ith unfinalized 
2de0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2df0: 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e  nts.** and/or un
2e00: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2e10: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2e20: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2e30: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2e40: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2e50: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2e60: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2e70: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2e80: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2e90: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ea0: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2eb0: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2ec0: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2ed0: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2ee0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2ef0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2f00: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2f10: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2f20: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2f30: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2f40: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2f50: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2f60: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2f70: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2f80: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2f90: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2fa0: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2fb0: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2fc0: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2fd0: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2fe0: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2ff0: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
3000: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
3010: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
3020: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
3030: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
3040: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
3050: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
3060: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
3070: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
3080: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
3090: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
30a0: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
30b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
30c0: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
30d0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30e0: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
30f0: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
3100: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
3110: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
3120: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
3130: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
3140: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
3150: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 5b  hen it returns [
3160: 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74  SQLITE_OK] and t
3170: 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  he deallocation.
3180: 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20  ** of resources 
3190: 69 73 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  is deferred unti
31a0: 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20  l all [prepared 
31b0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c  statements], [BL
31c0: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20  OB handles],.** 
31d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  and [sqlite3_bac
31e0: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65  kup] objects are
31f0: 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e   also destroyed.
3200: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73  .**.** ^If an [s
3210: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69  qlite3] object i
3220: 73 20 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c  s destroyed whil
3230: 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  e a transaction 
3240: 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20  is open,.** the 
3250: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61  transaction is a
3260: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
3270: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
3280: 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20  The C parameter 
3290: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
32a0: 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  e(C)] and [sqlit
32b0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a  e3_close_v2(C)].
32c0: 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
32d0: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
32e0: 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ter or an [sqlit
32f0: 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  e3] object point
3300: 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  er obtained.** f
3310: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
3320: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
3330: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  pen16()], or.** 
3340: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
3350: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65  ()], and not pre
3360: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a  viously closed..
3370: 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
3380: 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73  te3_close() or s
3390: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
33a0: 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  ) with a NULL po
33b0: 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  inter.** argumen
33c0: 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  t is a harmless 
33d0: 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45  no-op..*/.SQLITE
33e0: 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
33f0: 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
3400: 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b  close(sqlite3*);
3410: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
3420: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
3430: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
3440: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
3450: 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61  * The type for a
3460: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3470: 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c  on..** This is l
3480: 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63  egacy and deprec
3490: 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63  ated.  It is inc
34a0: 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  luded for histor
34b0: 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ical.** compatib
34c0: 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74  ility and is not
34d0: 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a   documented..*/.
34e0: 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71  typedef int (*sq
34f0: 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28  lite3_callback)(
3500: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
3510: 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a  , char**);../*.*
3520: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d  * CAPI3REF: One-
3530: 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75  Step Query Execu
3540: 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a  tion Interface.*
3550: 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
3560: 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  3.**.** The sqli
3570: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
3580: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
3590: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
35a0: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
35b0: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
35c0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
35d0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
35e0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
35f0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
3600: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
3610: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
3620: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
3630: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3640: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3650: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3660: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3670: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3680: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3690: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
36a0: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
36b0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
36c0: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
36d0: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
36e0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
36f0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
3700: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
3710: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
3720: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
3730: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3740: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3750: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3760: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3770: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3780: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3790: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
37a0: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
37b0: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
37c0: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
37d0: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
37e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
37f0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3800: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67  s relayed throug
3810: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67  h to the 1st arg
3820: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a  ument of each.**
3830: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61   callback invoca
3840: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63  tion.  ^If the c
3850: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  allback pointer 
3860: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3870: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ).** is NULL, th
3880: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69  en no callback i
3890: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61  s ever invoked a
38a0: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61  nd result rows a
38b0: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a  re.** ignored..*
38c0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  *.** ^If an erro
38d0: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65  r occurs while e
38e0: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51  valuating the SQ
38f0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
3900: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  sed into.** sqli
3910: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e  te3_exec(), then
3920: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
3930: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d  e current statem
3940: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a  ent stops and.**
3950: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74   subsequent stat
3960: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70  ements are skipp
3970: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68  ed.  ^If the 5th
3980: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3990: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
39a0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
39b0: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
39c0: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
39d0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
39e0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
39f0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
3a00: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  d passed back th
3a10: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
3a20: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61  rameter..** To a
3a30: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  void memory leak
3a40: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  s, the applicati
3a50: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  on should invoke
3a60: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3a70: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65  ].** on error me
3a80: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65  ssage strings re
3a90: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
3aa0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3ab0: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65   of.** of sqlite
3ac0: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74  3_exec() after t
3ad0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
3ae0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f   string is no lo
3af0: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20  nger needed..** 
3b00: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
3b10: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3b20: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3b30: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72  ULL and no error
3b40: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e  s.** occur, then
3b50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3b60: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72  sets the pointer
3b70: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61   in its 5th para
3b80: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c  meter to.** NULL
3b90: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
3ba0: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  g..**.** ^If an 
3bb0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3bc0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
3bd0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71  non-zero, the sq
3be0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3bf0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
3c00: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74  SQLITE_ABORT wit
3c10: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  hout invoking th
3c20: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e  e callback again
3c30: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20   and.** without 
3c40: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73  running any subs
3c50: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3c60: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
3c70: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  e 2nd argument t
3c80: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
3c90: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75  ec() callback fu
3ca0: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a  nction is the.**
3cb0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
3cc0: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
3cd0: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75  .  ^The 3rd argu
3ce0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3cf0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61  te3_exec().** ca
3d00: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
3d10: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3d20: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e  o strings obtain
3d30: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a  ed as if from.**
3d40: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3d50: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f  _text()], one fo
3d60: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20  r each column.  
3d70: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f  ^If an element o
3d80: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  f a.** result ro
3d90: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  w is NULL then t
3da0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
3db0: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
3dc0: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  for the.** sqlit
3dd0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3de0: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ck is a NULL poi
3df0: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20  nter.  ^The 4th 
3e00: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
3e10: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3e20: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  ) callback is an
3e30: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3e40: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68  rs to strings wh
3e50: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72  ere each.** entr
3e60: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65  y represents the
3e70: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70   name of corresp
3e80: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f  onding result co
3e90: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64  lumn as obtained
3ea0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3eb0: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
3ec0: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
3ed0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
3ee0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3ef0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
3f00: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  r, a pointer.** 
3f10: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
3f20: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ng, or a pointer
3f30: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f   that contains o
3f40: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
3f50: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f  nd/or .** SQL co
3f60: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20  mments, then no 
3f70: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
3f80: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
3f90: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
3fa0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e   is not changed.
3fb0: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69  .**.** Restricti
3fc0: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ons:.**.** <ul>.
3fd0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3fe0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e 73  ication must ens
3ff0: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74  ure that the 1st
4000: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
4010: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
4020: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20       is a valid 
4030: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  and open [databa
4040: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
4050: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4060: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4070: 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61   close the [data
4080: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
4090: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
40a0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61        the 1st pa
40b0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
40c0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
40d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
40e0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c  s running..** <l
40f0: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
4100: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69  on must not modi
4110: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  fy the SQL state
4120: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64  ment text passed
4130: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68   into.**      th
4140: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
4150: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
4160: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
4170: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
4180: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53  g..** </ul>.*/.S
4190: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
41a0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
41b0: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
41c0: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
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 2f 2a 20 41 6e 20 6f 70          /* An op
41f0: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
4200: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
4210: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4220: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
4230: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
4240: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
4250: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
4260: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
4270: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
4280: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
4290: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
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 2f 2a 20 31 73 74 20 61          /* 1st a
42c0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
42d0: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
42e0: 65 72 72 6d 73 67 20 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 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
4310: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
4320: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
4330: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
4340: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
4350: 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69  result code defi
4360: 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d  nitions}.**.** M
4370: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74  any SQLite funct
4380: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69  ions return an i
4390: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f  nteger result co
43a0: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20  de from the set 
43b0: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e  shown.** here in
43c0: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61   order to indica
43d0: 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61  te success or fa
43e0: 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  ilure..**.** New
43f0: 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79   error codes may
4400: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
4410: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
4420: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  SQLite..**.** Se
4430: 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64 65  e also: [extende
4440: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65  d result code de
4450: 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64  finitions].*/.#d
4460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20  efine SQLITE_OK 
4470: 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
4480: 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75   Successful resu
4490: 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69  lt */./* beginni
44a0: 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  ng-of-error-code
44b0: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  s */.#define SQL
44c0: 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20  ITE_ERROR       
44d0: 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f   1   /* SQL erro
44e0: 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74  r or missing dat
44f0: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
4500: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c   SQLITE_INTERNAL
4510: 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65       2   /* Inte
4520: 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72  rnal logic error
4530: 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64   in SQLite */.#d
4540: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52  efine SQLITE_PER
4550: 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a  M         3   /*
4560: 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69   Access permissi
4570: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
4580: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
4590: 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20  T        4   /* 
45a0: 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  Callback routine
45b0: 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62   requested an ab
45c0: 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ort */.#define S
45d0: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20  QLITE_BUSY      
45e0: 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61     5   /* The da
45f0: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c  tabase file is l
4600: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4610: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20   SQLITE_LOCKED  
4620: 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61       6   /* A ta
4630: 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62  ble in the datab
4640: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ase is locked */
4650: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4660: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20  NOMEM        7  
4670: 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66   /* A malloc() f
4680: 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ailed */.#define
4690: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
46a0: 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65       8   /* Atte
46b0: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72  mpt to write a r
46c0: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65  eadonly database
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20  TE_INTERRUPT    
46f0: 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  9   /* Operation
4700: 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73   terminated by s
4710: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
4720: 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ()*/.#define SQL
4730: 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20  ITE_IOERR       
4740: 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e  10   /* Some kin
4750: 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72  d of disk I/O er
4760: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a  ror occurred */.
4770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4780: 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20  ORRUPT     11   
4790: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
47a0: 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61  disk image is ma
47b0: 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69  lformed */.#defi
47c0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  ne SQLITE_NOTFOU
47d0: 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e  ND    12   /* Un
47e0: 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20  known opcode in 
47f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
4800: 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e  trol() */.#defin
4810: 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20  e SQLITE_FULL   
4820: 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73       13   /* Ins
4830: 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65  ertion failed be
4840: 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69  cause database i
4850: 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e  s full */.#defin
4860: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
4870: 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61  N    14   /* Una
4880: 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ble to open the 
4890: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20  PROTOCOL    15  
48c0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63   /* Database loc
48d0: 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72  k protocol error
48e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48f0: 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31  TE_EMPTY       1
4900: 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
4910: 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66  is empty */.#def
4920: 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d  ine SQLITE_SCHEM
4930: 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54  A      17   /* T
4940: 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
4950: 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64  ma changed */.#d
4960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f  efine SQLITE_TOO
4970: 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a  BIG      18   /*
4980: 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   String or BLOB 
4990: 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d  exceeds size lim
49a0: 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  it */.#define SQ
49b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
49c0: 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64   19   /* Abort d
49d0: 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74  ue to constraint
49e0: 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64   violation */.#d
49f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4a00: 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a  MATCH    20   /*
4a10: 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61   Data type misma
4a20: 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tch */.#define S
4a30: 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20  QLITE_MISUSE    
4a40: 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72    21   /* Librar
4a50: 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74  y used incorrect
4a60: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
4a70: 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20  LITE_NOLFS      
4a80: 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53   22   /* Uses OS
4a90: 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75   features not su
4aa0: 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20  pported on host 
4ab0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4ac0: 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33  E_AUTH        23
4ad0: 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74     /* Authorizat
4ae0: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
4af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52  efine SQLITE_FOR
4b00: 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a  MAT      24   /*
4b10: 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62   Auxiliary datab
4b20: 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72  ase format error
4b30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b40: 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32  TE_RANGE       2
4b50: 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d  5   /* 2nd param
4b60: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
4b70: 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67  bind out of rang
4b80: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4b90: 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20  ITE_NOTADB      
4ba0: 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65  26   /* File ope
4bb0: 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ned that is not 
4bc0: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
4bd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4be0: 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37  E_NOTICE      27
4bf0: 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69     /* Notificati
4c00: 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ons from sqlite3
4c10: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
4c20: 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47  e SQLITE_WARNING
4c30: 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72       28   /* War
4c40: 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74  nings from sqlit
4c50: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66  e3_log() */.#def
4c60: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
4c70: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
4c80: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
4c90: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
4ca0: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
4cb0: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4cc0: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4cd0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4ce0: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4cf0: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4d00: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4d10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4d20: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4d30: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
4d40: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4d50: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
4d60: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4d70: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4d80: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4d90: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4da0: 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74 65  n one of 30 inte
4db0: 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20 63  ger.** [result c
4dc0: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4dd0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4de0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4df0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4e00: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4e10: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4e20: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4e30: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4e40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4e50: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4e60: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4e70: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4e80: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4e90: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4ea0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4eb0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4ec0: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4ed0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4ee0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4ef0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4f00: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4f10: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4f20: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4f30: 73 2e 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64  s. These [extend
4f40: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
4f50: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20   are enabled or 
4f60: 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61  disabled.** on a
4f70: 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f   per database co
4f80: 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75  nnection basis u
4f90: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
4fa0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
4fb0: 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50  sult_codes()] AP
4fc0: 49 2e 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65  I.  Or, the exte
4fd0: 6e 64 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a  nded code for.**
4fe0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
4ff0: 20 65 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62   error can be ob
5000: 74 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  tained using.** 
5010: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
5020: 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f  d_errcode()]..*/
5030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5040: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
5050: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5060: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
5070: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5080: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
5090: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50a0: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
50b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50c0: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
50d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50e0: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
50f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5100: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
5110: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5120: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
5130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5140: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
5150: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5160: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
5170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5180: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
5190: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51a0: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
51b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
51c0: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
51d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51e0: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
51f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
5200: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
5210: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5220: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5230: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
5240: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5250: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5260: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5280: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
5290: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52a0: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
52c0: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
5300: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5320: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
5340: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5360: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
5380: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53a0: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
53c0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53e0: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
5400: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5420: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5440: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5460: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5480: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54a0: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
54c0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54e0: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5500: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5520: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5540: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5560: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
5580: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55a0: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
55c0: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55e0: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
55f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41  SQLITE_IOERR_MMA
5600: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  P              (
5610: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5620: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  24<<8)).#define 
5630: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54  SQLITE_IOERR_GET
5640: 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28  TEMPPATH       (
5650: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5660: 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  25<<8)).#define 
5670: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e  SQLITE_IOERR_CON
5680: 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20 28  VPATH          (
5690: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
56a0: 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  26<<8)).#define 
56b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f  SQLITE_IOERR_VNO
56c0: 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  DE             (
56d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
56e0: 32 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  27<<8)).#define 
56f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
5700: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
5710: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
5720: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5730: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
5740: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
5750: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
5760: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5770: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e  e SQLITE_BUSY_SN
5780: 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20  APSHOT          
5790: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
57a0: 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69  |  (2<<8)).#defi
57b0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
57c0: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
57d0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
57e0: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5800: 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20  OPEN_ISDIR      
5810: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5820: 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OPEN | (2<<8)).#
5830: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5840: 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20  NTOPEN_FULLPATH 
5850: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5860: 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29  NTOPEN | (3<<8))
5870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5880: 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54  CANTOPEN_CONVPAT
5890: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
58a0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38  CANTOPEN | (4<<8
58b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
58c0: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20  E_CORRUPT_VTAB  
58d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
58e0: 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c  E_CORRUPT | (1<<
58f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5900: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f  TE_READONLY_RECO
5910: 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49  VERY       (SQLI
5920: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31  TE_READONLY | (1
5930: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5940: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41  LITE_READONLY_CA
5950: 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51  NTLOCK       (SQ
5960: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5970: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5980: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5990: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28  ROLLBACK       (
59a0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
59b0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
59c0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
59d0: 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20  Y_DBMOVED       
59e0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
59f0: 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  Y | (4<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
5a10: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54     (SQLITE_ABORT
5a30: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5a40: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5a50: 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20  AINT_CHECK      
5a60: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a70: 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AINT | (1<<8)).#
5a80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a90: 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48  NSTRAINT_COMMITH
5aa0: 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  OOK   (SQLITE_CO
5ab0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38  NSTRAINT | (2<<8
5ac0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5ad0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52  E_CONSTRAINT_FOR
5ae0: 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54  EIGNKEY   (SQLIT
5af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5b00: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5b10: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b20: 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53  _FUNCTION     (S
5b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b40: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5b50: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5b60: 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20  AINT_NOTNULL    
5b70: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5b80: 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23  AINT | (5<<8)).#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5ba0: 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59  NSTRAINT_PRIMARY
5bb0: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
5bc0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38  NSTRAINT | (6<<8
5bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5be0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49  E_CONSTRAINT_TRI
5bf0: 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 54  GGER      (SQLIT
5c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5c10: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
5c20: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c30: 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 53  _UNIQUE       (S
5c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c50: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
5c60: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c70: 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20  AINT_VTAB       
5c80: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5c90: 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23  AINT | (9<<8)).#
5ca0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cb0: 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20  NSTRAINT_ROWID  
5cc0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5cd0: 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38  NSTRAINT |(10<<8
5ce0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5cf0: 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52  E_NOTICE_RECOVER
5d00: 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54  _WAL      (SQLIT
5d10: 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38  E_NOTICE | (1<<8
5d20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d30: 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52  E_NOTICE_RECOVER
5d40: 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54  _ROLLBACK (SQLIT
5d50: 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38  E_NOTICE | (2<<8
5d60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d70: 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e  E_WARNING_AUTOIN
5d80: 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49 54  DEX       (SQLIT
5d90: 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c  E_WARNING | (1<<
5da0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5db0: 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20  TE_AUTH_USER    
5dc0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5dd0: 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29  TE_AUTH | (1<<8)
5de0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5df0: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5e00: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5e10: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5e20: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5e30: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5e40: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5e50: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5e60: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5e70: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5e80: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5e90: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5ea0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
5eb0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
5ec0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5ed0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5ee0: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5ef0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5f00: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f20: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5f30: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5f40: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5f50: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5f60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f70: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
5f80: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
5f90: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5fa0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5fc0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5fd0: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5fe0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6000: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
6010: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
6020: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6040: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
6050: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
6060: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6080: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
6090: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
60a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
60b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
60c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60d0: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
60e0: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
60f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6100: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6120: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
6130: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
6140: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6160: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
6170: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
6180: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6190: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61a0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
61b0: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
61c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61e0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
61f0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
6200: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6210: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6220: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
6230: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
6240: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6260: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
6270: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
6280: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62a0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
62b0: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
62c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62e0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
62f0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
6300: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6310: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6320: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6330: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
6340: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
6350: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6360: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6380: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
6390: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
63a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
63b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
63c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
63d0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
63e0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
63f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6400: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6420: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
6430: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
6440: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
6450: 20 52 65 73 65 72 76 65 64 3a 20 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 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
6480: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6490: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
64a0: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
64b0: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
64c0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
64d0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
64e0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
64f0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
6500: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
6510: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
6520: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
6530: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
6540: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
6550: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
6560: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
6570: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
6580: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
6590: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
65a0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
65b0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
65c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
65d0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
65e0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
65f0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
6600: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6610: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6620: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
6630: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
6640: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
6650: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
6660: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
6670: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
6680: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
6690: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
66a0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
66b0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
66c0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
66d0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
66e0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
66f0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
6700: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
6710: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
6720: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
6730: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
6740: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
6750: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
6760: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
6770: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6780: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
6790: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
67a0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
67b0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
67c0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
67d0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
67e0: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68  to xWrite().  Th
67f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
6800: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
6810: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  TE property mean
6820: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20  s that.** after 
6830: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67  reboot following
6840: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65   a crash or powe
6850: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79  r loss, the only
6860: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66   bytes in a.** f
6870: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72  ile that were wr
6880: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70  itten at the app
6890: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d  lication level m
68a0: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65  ight have change
68b0: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64  d.** and that ad
68c0: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76  jacent bytes, ev
68d0: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20  en bytes within 
68e0: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20  the same sector 
68f0: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  are.** guarantee
6900: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65  d to be unchange
6910: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6920: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6930: 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c  _WHEN_OPEN.** fl
6940: 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  ag indicate that
6950: 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62   a file cannot b
6960: 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f  e deleted when o
6970: 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c  pen.  The.** SQL
6980: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
6990: 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74  BLE flag indicat
69a0: 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c 65  es that the file
69b0: 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f   is on.** read-o
69c0: 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61  nly media and ca
69d0: 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
69e0: 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65  even by processe
69f0: 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74  s with.** elevat
6a00: 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a  ed privileges..*
6a10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6a20: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
6a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6a40: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
6a50: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6a60: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20  OMIC512         
6a70: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
6a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6a90: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
6aa0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6ab0: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
6ac0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6ad0: 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC2K            
6ae0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
6af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6b00: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
6b10: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6b20: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
6b30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6b40: 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  8K              
6b50: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
6b60: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6b70: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
6b80: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6b90: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
6ba0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
6bb0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6bc0: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
6bd0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6be0: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20  TOMIC64K        
6bf0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
6c00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c10: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6c20: 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30  D            0x0
6c30: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
6c40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6c50: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20  UENTIAL         
6c60: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
6c70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6c80: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
6c90: 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30  WHEN_OPEN  0x000
6ca0: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
6cb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
6cc0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
6cd0: 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65    0x00001000.#de
6ce0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6cf0: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20  P_IMMUTABLE     
6d00: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32           0x00002
6d10: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
6d20: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
6d30: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
6d40: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
6d50: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
6d60: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6d70: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
6d80: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
6d90: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
6da0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
6db0: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
6dc0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6dd0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
6de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6df0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
6e00: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
6e10: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
6e20: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
6e30: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
6e40: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
6e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6e60: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
6e70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6e80: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
6e90: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6ea0: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
6eb0: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
6ec0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
6ed0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
6ee0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
6ef0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6f00: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6f10: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
6f20: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
6f30: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6f40: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6f50: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
6f60: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
6f70: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6f80: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
6f90: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
6fa0: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
6fb0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
6fc0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
6fd0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
6fe0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
6ff0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
7000: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
7010: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
7020: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
7030: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
7040: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
7050: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
7060: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
7070: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
7080: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
7090: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
70a0: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
70b0: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
70c0: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
70d0: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
70e0: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
70f0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
7100: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7110: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
7120: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
7130: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
7140: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
7150: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
7160: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
7170: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
7180: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
7190: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
71a0: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
71b0: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
71c0: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
71d0: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
71e0: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
71f0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
7200: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
7210: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7220: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7230: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
7240: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
7250: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
7260: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
7270: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
7280: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
7290: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
72a0: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
72b0: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
72c0: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
72d0: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
72e0: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
72f0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
7300: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
7310: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
7320: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7330: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
7340: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
7350: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
7360: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
7370: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
7380: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
7390: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
73a0: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
73b0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
73c0: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
73d0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
73e0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
73f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
7400: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7410: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
7420: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
7430: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7440: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
7450: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
7460: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
7470: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
7480: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
7490: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
74a0: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
74b0: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
74c0: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
74d0: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
74e0: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
74f0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
7500: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
7510: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
7520: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
7530: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
7540: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
7550: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
7560: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
7570: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7580: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
7590: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
75a0: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
75b0: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
75c0: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
75d0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
75e0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
75f0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
7600: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
7610: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
7620: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
7630: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
7640: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
7650: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
7660: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7670: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7680: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
7690: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
76a0: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
76b0: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
76c0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
76d0: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
76e0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
76f0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
7700: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
7710: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
7720: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
7730: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
7740: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
7750: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
7760: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
7770: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
7780: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
7790: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
77a0: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
77b0: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
77c0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
77d0: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
77e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
77f0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
7800: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7810: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
7820: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
7830: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7840: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
7850: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
7860: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
7870: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
7880: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
7890: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
78a0: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
78b0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
78c0: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
78d0: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
78e0: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
78f0: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
7900: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
7910: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
7920: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
7930: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7940: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
7950: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
7960: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
7970: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
7980: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
7990: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
79a0: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
79b0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
79c0: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
79d0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
79e0: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
79f0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
7a00: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
7a10: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
7a20: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
7a30: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
7a40: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
7a50: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
7a60: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
7a70: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
7a80: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
7a90: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
7aa0: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
7ab0: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
7ac0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
7ad0: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
7ae0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
7af0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
7b00: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
7b10: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7b20: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
7b30: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
7b40: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7b50: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
7b60: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7b70: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
7b80: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
7b90: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7ba0: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
7bb0: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
7bc0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
7bd0: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
7be0: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
7bf0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
7c00: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
7c10: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
7c20: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
7c30: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
7c40: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
7c50: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
7c60: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
7c70: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
7c80: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
7c90: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
7ca0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
7cb0: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
7cc0: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
7cd0: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
7ce0: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
7cf0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
7d00: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
7d10: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
7d20: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
7d30: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
7d40: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
7d50: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
7d60: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
7d70: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
7d80: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7d90: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
7da0: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
7db0: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
7dc0: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
7dd0: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
7de0: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
7df0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
7e00: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
7e10: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
7e20: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
7e30: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
7e40: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
7e50: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
7e60: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
7e70: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
7e80: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
7e90: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
7ea0: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
7eb0: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
7ec0: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
7ed0: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
7ee0: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
7ef0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
7f00: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
7f10: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
7f20: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
7f30: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
7f40: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
7f50: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
7f60: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
7f70: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
7f80: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
7f90: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66  own use..** A [f
7fa0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
7fb0: 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  des | list of op
7fc0: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
7fd0: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
7fe0: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
7ff0: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
8000: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
8010: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
8020: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a  ld use opcodes.*
8030: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
8040: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
8050: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c  licts.  VFS impl
8060: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
8070: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
8080: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66  LITE_NOTFOUND] f
8090: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  or file control 
80a0: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65  opcodes that the
80b0: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f  y do not.** reco
80c0: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  gnize..**.** The
80d0: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
80e0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
80f0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
8100: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
8110: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
8120: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
8130: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
8140: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
8150: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
8160: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
8170: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
8180: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
8190: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
81a0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
81b0: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
81c0: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
81d0: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
81e0: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
81f0: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
8200: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
8210: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8220: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
8230: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8240: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
8250: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8260: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
8270: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8280: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
8290: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82a0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
82b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82c0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
82d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
82f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8300: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
8310: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8320: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
8330: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8340: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
8350: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
8360: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8370: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  NTIAL].** </ul>.
8380: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
8390: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
83a0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
83b0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
83c0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
83d0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
83e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
83f0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
8400: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
8410: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
8420: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
8430: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
8440: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
8450: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
8460: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
8470: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
8480: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
8490: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
84a0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
84b0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
84c0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
84d0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
84e0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
84f0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
8500: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
8510: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
8520: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
8530: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
8540: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8550: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
8560: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
8570: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
8580: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
8590: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
85a0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
85b0: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a  to xWrite()..**.
85c0: 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65  ** If xRead() re
85d0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45  turns SQLITE_IOE
85e0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74  RR_SHORT_READ it
85f0: 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a   must also fill.
8600: 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64  ** in the unread
8610: 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65   portions of the
8620: 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72   buffer with zer
8630: 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a  os.  A VFS that.
8640: 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f  ** fails to zero
8650: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
8660: 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20  s might seem to 
8670: 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a  work.  However,.
8680: 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65  ** failure to ze
8690: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
86a0: 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ads will eventua
86b0: 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64  lly lead to.** d
86c0: 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
86d0: 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
86e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
86f0: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
8700: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
8710: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8720: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
8730: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
8740: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
8750: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8760: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
8770: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
8780: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
8790: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
87a0: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71  int (*xWrite)(sq
87b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e  lite3_file*, con
87c0: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  st void*, int iA
87d0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
87e0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
87f0: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c  (*xTruncate)(sql
8800: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8810: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b  te3_int64 size);
8820: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
8830: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8840: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
8850: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71   (*xFileSize)(sq
8860: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8870: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a  ite3_int64 *pSiz
8880: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
8890: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
88a0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
88b0: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
88c0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
88d0: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
88e0: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
88f0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52  3_file*, int *pR
8900: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
8910: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71  xFileControl)(sq
8920: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8930: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29   op, void *pArg)
8940: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f  ;.  int (*xSecto
8950: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  rSize)(sqlite3_f
8960: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8970: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8980: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66  stics)(sqlite3_f
8990: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  ile*);.  /* Meth
89a0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
89b0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
89c0: 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68  1 */.  int (*xSh
89d0: 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  mMap)(sqlite3_fi
89e0: 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e  le*, int iPg, in
89f0: 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69  t pgsz, int, voi
8a00: 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20  d volatile**);. 
8a10: 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29   int (*xShmLock)
8a20: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8a30: 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20  int offset, int 
8a40: 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  n, int flags);. 
8a50: 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72   void (*xShmBarr
8a60: 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ier)(sqlite3_fil
8a70: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  e*);.  int (*xSh
8a80: 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f  mUnmap)(sqlite3_
8a90: 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74  file*, int delet
8aa0: 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74  eFlag);.  /* Met
8ab0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
8ac0: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8ad0: 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46   2 */.  int (*xF
8ae0: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
8af0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8b00: 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41  64 iOfst, int iA
8b10: 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a  mt, void **pp);.
8b20: 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68    int (*xUnfetch
8b30: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8b40: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8b50: 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a  Ofst, void *p);.
8b60: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8b70: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8b80: 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20   version 3 */.  
8b90: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
8ba0: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
8bb0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
8bc0: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
8bd0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
8be0: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
8bf0: 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45  ol Opcodes.** KE
8c00: 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f  YWORDS: {file co
8c10: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b  ntrol opcodes} {
8c20: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8c30: 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ode}.**.** These
8c40: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
8c50: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
8c60: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
8c70: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
8c80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
8c90: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8ca0: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
8cb0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
8cc0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
8cd0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce..**.** <ul>.*
8ce0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8cf0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d  CNTL_LOCKSTATE]]
8d00: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8d10: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
8d20: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8d30: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
8d40: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
8d50: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
8d60: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
8d70: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
8d80: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
8d90: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
8da0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
8db0: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
8dc0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
8dd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
8de0: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
8df0: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
8e00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
8e10: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
8e20: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
8e30: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
8e40: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
8e50: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
8e60: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
8e70: 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e  esting and is on
8e80: 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65  ly available whe
8e90: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53  n the SQLITE_TES
8ea0: 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  T.** compile-tim
8eb0: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  e option is used
8ec0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
8ed0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8ee0: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  HINT]].** The [S
8ef0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
8f00: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
8f10: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
8f20: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
8f30: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
8f40: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
8f50: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
8f60: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
8f70: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
8f80: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
8f90: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
8fa0: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
8fb0: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
8fc0: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
8fd0: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
8fe0: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
8ff0: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
9000: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
9010: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
9020: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
9030: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
9040: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
9050: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
9060: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
9070: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9080: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
9090: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
90a0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
90b0: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
90c0: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
90d0: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
90e0: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
90f0: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
9100: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
9110: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
9120: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
9130: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
9140: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
9150: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9160: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
9170: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
9180: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
9190: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
91a0: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
91b0: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
91c0: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
91d0: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
91e0: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
91f0: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
9200: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
9210: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
9220: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
9230: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
9240: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
9250: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
9260: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
9270: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9280: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
9290: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
92a0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
92b0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
92c0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
92d0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
92e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
92f0: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9300: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
9310: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
9320: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
9330: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ee the [sqlite3_
9340: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9350: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
9360: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
9370: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
9380: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9390: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
93a0: 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65  ED]].** No longe
93b0: 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  r in use..**.** 
93c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
93d0: 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65  TL_SYNC]].** The
93e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
93f0: 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  YNC] opcode is g
9400: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
9410: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e  lly by SQLite an
9420: 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65  d.** sent to the
9430: 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79   VFS immediately
9440: 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e   before the xSyn
9450: 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  c method is invo
9460: 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61  ked on a.** data
9470: 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69  base file descri
9480: 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65  ptor. Or, if the
9490: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
94a0: 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a   not invoked .**
94b0: 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65   because the use
94c0: 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64  r has configured
94d0: 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a   SQLite with .**
94e0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
94f0: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79  nous | PRAGMA sy
9500: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69  nchronous=OFF] i
9510: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20  t is invoked in 
9520: 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65  place .** of the
9530: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49   xSync method. I
9540: 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68  n most cases, th
9550: 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
9560: 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a  nt passed with.*
9570: 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  * this file-cont
9580: 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77  rol is NULL. How
9590: 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74  ever, if the dat
95a0: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65  abase file is be
95b0: 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73  ing synced.** as
95c0: 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69   part of a multi
95d0: 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74  -database commit
95e0: 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70  , the argument p
95f0: 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74  oints to a nul-t
9600: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
9610: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
9620: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  he transactions 
9630: 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66  master-journal f
9640: 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20  ile name. VFSes 
9650: 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20  that .** do not 
9660: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9670: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
9680: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
9690: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
96a0: 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  s .** should not
96b0: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
96c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
96d0: 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ith this opcode 
96e0: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
96f0: 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20  .** disrupt the 
9700: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
9710: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
9720: 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  es that do requi
9730: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
9740: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9750: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
9760: 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  O]].** The [SQLI
9770: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
9780: 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65  PHASETWO] opcode
9790: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
97a0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
97b0: 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74  te.** and sent t
97c0: 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20  o the VFS after 
97d0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61  a transaction ha
97e0: 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64  s been committed
97f0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
9800: 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64  but before the d
9810: 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63  atabase is unloc
9820: 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20  ked. VFSes that 
9830: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
9840: 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c   signal.** shoul
9850: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
9860: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
9870: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
9880: 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b  ld not call.** [
9890: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
98a0: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
98b0: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
98c0: 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74  g so may disrupt
98d0: 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69   the .** operati
98e0: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
98f0: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
9900: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
9910: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
9920: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
9930: 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e  _AV_RETRY]].** ^
9940: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9950: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
9960: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9970: 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75   to configure au
9980: 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79  tomatic.** retry
9990: 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65   counts and inte
99a0: 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69  rvals for certai
99b0: 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61  n disk I/O opera
99c0: 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a  tions for the.**
99d0: 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69   windows [VFS] i
99e0: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
99f0: 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e  de robustness in
9a00: 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   the presence of
9a10: 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70  .** anti-virus p
9a20: 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66  rograms.  By def
9a30: 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77  ault, the window
9a40: 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79  s VFS will retry
9a50: 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66   file read,.** f
9a60: 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66  ile write, and f
9a70: 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61  ile delete opera
9a80: 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74  tions up to 10 t
9a90: 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c  imes, with a del
9aa0: 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c  ay.** of 25 mill
9ab0: 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20  iseconds before 
9ac0: 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20  the first retry 
9ad0: 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c  and with the del
9ae0: 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a  ay increasing.**
9af0: 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61   by an additiona
9b00: 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  l 25 millisecond
9b10: 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73  s with each subs
9b20: 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54  equent retry.  T
9b30: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c  his.** opcode al
9b40: 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76  lows these two v
9b50: 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65  alues (10 retrie
9b60: 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65  s and 25 millise
9b70: 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a  conds of delay).
9b80: 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65  ** to be adjuste
9b90: 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61  d.  The values a
9ba0: 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61  re changed for a
9bb0: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ll database conn
9bc0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69  ections.** withi
9bd0: 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
9be0: 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  ss.  The argumen
9bf0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
9c00: 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  o an array of tw
9c10: 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68  o.** integers wh
9c20: 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e  ere the first in
9c30: 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20  teger i the new 
9c40: 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20  retry count and 
9c50: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e  the second.** in
9c60: 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c  teger is the del
9c70: 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69  ay.  If either i
9c80: 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69  nteger is negati
9c90: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74  ve, then the set
9ca0: 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  ting.** is not c
9cb0: 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65  hanged but inste
9cc0: 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ad the prior val
9cd0: 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69  ue of that setti
9ce0: 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  ng is written.**
9cf0: 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20   into the array 
9d00: 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20  entry, allowing 
9d10: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72  the current retr
9d20: 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65  y settings to be
9d30: 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64  .** interrogated
9d40: 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70  .  The zDbName p
9d50: 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f  arameter is igno
9d60: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  red..**.** <li>[
9d70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
9d80: 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e  RSIST_WAL]].** ^
9d90: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9da0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f  L_PERSIST_WAL] o
9db0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9dc0: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
9dd0: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
9de0: 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65  [WAL | Write Ahe
9df0: 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e  ad Log] setting.
9e00: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
9e10: 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77  e auxiliary.** w
9e20: 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61  rite ahead log a
9e30: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
9e40: 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20   files used for 
9e50: 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  transaction cont
9e60: 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d  rol.** are autom
9e70: 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
9e80: 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74   when the latest
9e90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74   connection to t
9ea0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
9eb0: 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20  loses.  Setting 
9ec0: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
9ed0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65  ode causes those
9ee0: 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73   files to persis
9ef0: 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65  t after.** close
9f00: 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68  .  Persisting th
9f10: 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75  e files is usefu
9f20: 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f  l when other pro
9f30: 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e  cesses that do n
9f40: 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65  ot.** have write
9f50: 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74   permission on t
9f60: 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e  he directory con
9f70: 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61  taining the data
9f80: 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a  base file want.*
9f90: 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61  * to read the da
9fa0: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20  tabase file, as 
9fb0: 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72  the WAL and shar
9fc0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
9fd0: 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e  must exist.** in
9fe0: 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64   order for the d
9ff0: 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
a000: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75  adable.  The fou
a010: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a020: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a030: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a040: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a050: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a060: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a070: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a080: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a090: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
a0a0: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
a0b0: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a  le persistent.**
a0c0: 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74   WAL mode.  If t
a0d0: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
a0e0: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
a0f0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
a100: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c  e current.** WAL
a110: 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74   persistence set
a120: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
a130: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a140: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
a150: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
a160: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a170: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a180: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
a190: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
a1a0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
a1b0: 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72   "powersafe-over
a1c0: 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22  write" or "PSOW"
a1d0: 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50   setting.  The P
a1e0: 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64  SOW setting.** d
a1f0: 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53  etermines the [S
a200: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
a210: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a220: 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78   bit of the.** x
a230: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
a240: 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54  stics methods. T
a250: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a260: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
a270: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a280: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
a290: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
a2a0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
a2b0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
a2c0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
a2d0: 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  sable zero-damag
a2e0: 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  e mode or 1 to e
a2f0: 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  nable zero-damag
a300: 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74  e.** mode.  If t
a310: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
a320: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
a330: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
a340: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72  e current.** zer
a350: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65  o-damage mode se
a360: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
a370: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a380: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
a390: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a3a0: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  L_OVERWRITE] opc
a3b0: 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ode is invoked b
a3c0: 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f  y SQLite after o
a3d0: 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74  pening.** a writ
a3e0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f  e transaction to
a3f0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20   indicate that, 
a400: 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c  unless it is rol
a410: 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d  led back for som
a420: 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65  e.** reason, the
a430: 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65   entire database
a440: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76   file will be ov
a450: 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65  erwritten by the
a460: 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61   current .** tra
a470: 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69  nsaction. This i
a480: 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d  s used by VACUUM
a490: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
a4a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a4b0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a  FCNTL_VFSNAME]].
a4c0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a4d0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f  FCNTL_VFSNAME] o
a4e0: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
a4f0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
a500: 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20  names of.** all 
a510: 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56  [VFSes] in the V
a520: 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e  FS stack.  The n
a530: 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20  ames are of all 
a540: 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68  VFS shims and th
a550: 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f  e.** final botto
a560: 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20  m-level VFS are 
a570: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
a580: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
a590: 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
a5a0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65  alloc()] and the
a5b0: 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65   result is store
a5c0: 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76  d in the char* v
a5d0: 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20  ariable.** that 
a5e0: 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
a5f0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
a600: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a610: 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54   points to..** T
a620: 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73  he caller is res
a630: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65  ponsible for fre
a640: 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20  eing the memory 
a650: 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77  when done.  As w
a660: 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d  ith.** all file-
a670: 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c  control actions,
a680: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61   there is no gua
a690: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73  rantee that this
a6a0: 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a   will actually.*
a6b0: 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20  * do anything.  
a6c0: 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69  Callers should i
a6d0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68  nitialize the ch
a6e0: 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20  ar* variable to 
a6f0: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
a700: 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66  r in case this f
a710: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e  ile-control is n
a720: 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20  ot implemented. 
a730: 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   This file-contr
a740: 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65  ol.** is intende
a750: 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63  d for diagnostic
a760: 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a   use only..**.**
a770: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a780: 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20  NTL_PRAGMA]].** 
a790: 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41  ^Whenever a [PRA
a7a0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  GMA] statement i
a7b0: 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51  s parsed, an [SQ
a7c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a7d0: 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  A] .** file cont
a7e0: 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74  rol is sent to t
a7f0: 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33  he open [sqlite3
a800: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f  _file] object co
a810: 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74  rresponding.** t
a820: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
a830: 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65  ile to which the
a840: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
a850: 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61  t refers. ^The a
a860: 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68  rgument.** to th
a870: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a880: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
a890: 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79  trol is an array
a8a0: 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20   of.** pointers 
a8b0: 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72  to strings (char
a8c0: 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65  **) in which the
a8d0: 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20   second element 
a8e0: 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20  of the array.** 
a8f0: 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
a900: 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68  he pragma and th
a910: 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20  e third element 
a920: 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
a930: 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61  to the.** pragma
a940: 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
a950: 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72  pragma has no ar
a960: 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61  gument.  ^The ha
a970: 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20  ndler for an.** 
a980: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a990: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
a9a0: 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c  ol can optionall
a9b0: 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74  y make the first
a9c0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74   element.** of t
a9d0: 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65  he char** argume
a9e0: 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  nt point to a st
a9f0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72  ring obtained fr
aa00: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  om [sqlite3_mpri
aa10: 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65  ntf()].** or the
aa20: 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20   equivalent and 
aa30: 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c  that string will
aa40: 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75   become the resu
aa50: 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  lt of the pragma
aa60: 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72   or.** the error
aa70: 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20   message if the 
aa80: 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49  pragma fails. ^I
aa90: 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
aaa0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
aab0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
aac0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  rns [SQLITE_NOTF
aad0: 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d  OUND], then norm
aae0: 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20  al .** [PRAGMA] 
aaf0: 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69  processing conti
ab00: 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b  nues.  ^If the [
ab10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ab20: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
ab30: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
ab40: 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74  LITE_OK], then t
ab50: 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65  he parser assume
ab60: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46  s that the.** VF
ab70: 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68  S has handled th
ab80: 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20  e PRAGMA itself 
ab90: 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67  and the parser g
aba0: 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70  enerates a no-op
abb0: 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
abc0: 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c 74  tement if result
abd0: 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c   string is NULL,
abe0: 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e 73   or that returns
abf0: 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
ac00: 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20  e result string 
ac10: 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  if the string is
ac20: 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49   non-NULL..** ^I
ac30: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
ac40: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
ac50: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
ac60: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
ac70: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
ac80: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
ac90: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
aca0: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
acb0: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
acc0: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
acd0: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
ace0: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
acf0: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
ad00: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
ad10: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
ad20: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
ad30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ad40: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
ad50: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
ad60: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
ad70: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
ad80: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
ad90: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
ada0: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
adb0: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
adc0: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ments..**.** <li
add0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
ade0: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a  BUSYHANDLER]].**
adf0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ae00: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
ae10: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
ae20: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
ae30: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
ae40: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
ae50: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
ae60: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
ae70: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
ae80: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
ae90: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
aea0: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
aeb0: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
aec0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
aed0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
aee0: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
aef0: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
af00: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
af10: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
af20: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
af30: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
af40: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
af50: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
af60: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
af70: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
af80: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
af90: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
afa0: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
afb0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
afc0: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
afd0: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
afe0: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
aff0: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
b000: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
b010: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
b020: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
b030: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
b040: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
b050: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
b060: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
b070: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
b080: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
b090: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
b0a0: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20  MPFILENAME]].** 
b0b0: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e  ^Application can
b0c0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c   invoke the [SQL
b0d0: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
b0e0: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e  LENAME] file-con
b0f0: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20  trol.** to have 
b100: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20  SQLite generate 
b110: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  a.** temporary f
b120: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68  ilename using th
b130: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
b140: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65   that is followe
b150: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a  d to generate.**
b160: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
b170: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61  ames for TEMP ta
b180: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69  bles and other i
b190: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54  nternal uses.  T
b1a0: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  he.** argument s
b1b0: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a  hould be a char*
b1c0: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20  * which will be 
b1d0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
b1e0: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74  filename.** writ
b1f0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
b200: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
b210: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
b220: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68  .  The caller sh
b230: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b  ould.** invoke [
b240: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
b250: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f  on the result to
b260: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
b270: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  leak..**.** <li>
b280: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  [[SQLITE_FCNTL_M
b290: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  MAP_SIZE]].** Th
b2a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b2b0: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
b2c0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b2d0: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20  to query or set 
b2e0: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e  the.** maximum n
b2f0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74  umber of bytes t
b300: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64  hat will be used
b310: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70   for memory-mapp
b320: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61  ed I/O..** The a
b330: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
b340: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20  nter to a value 
b350: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f  of type sqlite3_
b360: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73  int64 that.** is
b370: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78   an advisory max
b380: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b390: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
b3a0: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20   to memory map. 
b3b0: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   The.** pointer 
b3c0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
b3d0: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75  ith the old valu
b3e0: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73  e.  The limit is
b3f0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a   not changed if.
b400: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69  ** the value ori
b410: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20  ginally pointed 
b420: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
b430: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65  and so the curre
b440: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e  nt limit .** can
b450: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70   be queried by p
b460: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e  assing in a poin
b470: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76  ter to a negativ
b480: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a  e number.  This.
b490: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
b4a0: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
b4b0: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ly to implement 
b4c0: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
b4d0: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  e]..**.** <li>[[
b4e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b4f0: 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  CE]].** The [SQL
b500: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b510: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72   file control pr
b520: 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20  ovides advisory 
b530: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74  information.** t
b540: 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20  o the VFS about 
b550: 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20  what the higher 
b560: 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51  layers of the SQ
b570: 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64  Lite stack are d
b580: 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69  oing..** This fi
b590: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b5a0: 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61  ed by some VFS a
b5b0: 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20  ctivity tracing 
b5c0: 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20  [shims]..** The 
b5d0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65  argument is a ze
b5e0: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
b5f0: 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61  ring.  Higher la
b600: 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53  yers in the.** S
b610: 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20  QLite stack may 
b620: 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63  generate instanc
b630: 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  es of this file 
b640: 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68  control if.** th
b650: 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43  e [SQLITE_USE_FC
b660: 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69  NTL_TRACE] compi
b670: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
b680: 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
b690: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b6a0: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a  NTL_HAS_MOVED]].
b6b0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b6c0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20  CNTL_HAS_MOVED] 
b6d0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74  file control int
b6e0: 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75  erprets its argu
b6f0: 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69  ment as a.** poi
b700: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
b710: 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73  er and it writes
b720: 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20   a boolean into 
b730: 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70  that integer dep
b740: 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65  ending.** on whe
b750: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
b760: 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65  file has been re
b770: 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72  named, moved, or
b780: 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69   deleted since i
b790: 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f  t.** was first o
b7a0: 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  pened..**.** <li
b7b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b7c0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
b7d0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b7e0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
b7f0: 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65  T_HANDLE] opcode
b800: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
b810: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
b820: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
b830: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
b840: 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74  method to swap t
b850: 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77  he file handle w
b860: 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70  ith the one.** p
b870: 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
b880: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20   pArg argument. 
b890: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
b8a0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
b8b0: 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f  testing.** and o
b8c0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
b8d0: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
b8e0: 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65  QLITE_TEST is de
b8f0: 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  fined..**.** <li
b900: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b910: 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54  WAL_BLOCK]].** T
b920: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b930: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61  _WAL_BLOCK] is a
b940: 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 56   signal to the V
b950: 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69 74  FS layer that it
b960: 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 76   might.** be adv
b970: 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f  antageous to blo
b980: 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 57  ck on the next W
b990: 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c  AL lock if the l
b9a0: 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64  ock is not immed
b9b0: 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61  iately.** availa
b9c0: 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73 75  ble.  The WAL su
b9d0: 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20 74  bsystem issues t
b9e0: 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69 6e  his signal durin
b9f0: 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d  g rare.** circum
ba00: 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 72  stances in order
ba10: 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c 65   to fix a proble
ba20: 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79 20  m with priority 
ba30: 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70  inversion..** Ap
ba40: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
ba50: 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75  d <em>not</em> u
ba60: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
ba70: 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  trol..**.** <li>
ba80: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a  [[SQLITE_FCNTL_Z
ba90: 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b  IPVFS]].** The [
baa0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
bab0: 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  VFS] opcode is i
bac0: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a 69  mplemented by zi
bad0: 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f  pvfs only. All o
bae0: 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75  ther.** VFS shou
baf0: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
bb00: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 68  _NOTFOUND for th
bb10: 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a  is opcode..**.**
bb20: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
bb30: 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65  NTL_RBU]].** The
bb40: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52   [SQLITE_FCNTL_R
bb50: 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d  BU] opcode is im
bb60: 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68 65  plemented by the
bb70: 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73 65   special VFS use
bb80: 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55 20  d by.** the RBU 
bb90: 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20  extension only. 
bba0: 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 73   All other VFS s
bbb0: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c  hould return SQL
bbc0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72  ITE_NOTFOUND for
bbd0: 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  .** this opcode.
bbe0: 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23    .** </ul>.*/.#
bbf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bc00: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
bc10: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
bc20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bc30: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
bc40: 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65  FILE       2.#de
bc50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bc60: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
bc70: 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66  ILE       3.#def
bc80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bc90: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
bca0: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
bcb0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bcc0: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
bcd0: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
bce0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
bcf0: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
bd00: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
bd10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
bd20: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
bd30: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
bd40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
bd50: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
bd60: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
bd70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
bd80: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
bd90: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
bda0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
bdb0: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
bdc0: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
bdd0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
bde0: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
bdf0: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
be00: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
be10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
be20: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
be30: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
be40: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
be50: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
be60: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
be70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
be80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
be90: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
bea0: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a  R            15.
beb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bec0: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
bed0: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23  E           16.#
bee0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bef0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  NTL_MMAP_SIZE   
bf00: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64             18.#d
bf10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bf20: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20  TL_TRACE        
bf30: 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65            19.#de
bf40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bf50: 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20  L_HAS_MOVED     
bf60: 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66           20.#def
bf70: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bf80: 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  _SYNC           
bf90: 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69          21.#defi
bfa0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bfb0: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20  COMMIT_PHASETWO 
bfc0: 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e         22.#defin
bfd0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
bfe0: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20  IN32_SET_HANDLE 
bff0: 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65        23.#define
c000: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41   SQLITE_FCNTL_WA
c010: 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  L_BLOCK         
c020: 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20       24.#define 
c030: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
c040: 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20  VFS             
c050: 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53      25.#define S
c060: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20  QLITE_FCNTL_RBU 
c070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c080: 20 20 20 32 36 0a 0a 2f 2a 20 64 65 70 72 65 63     26../* deprec
c090: 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64  ated names */.#d
c0a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
c0b0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
c0c0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
c0d0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
c0e0: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
c0f0: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
c100: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
c110: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
c120: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
c130: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e  SQLITE_LAST_ERRN
c140: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51  O             SQ
c150: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
c160: 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  ERRNO.../*.** CA
c170: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
c180: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
c190: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
c1a0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
c1b0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
c1c0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
c1d0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
c1e0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
c1f0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
c200: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
c210: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
c220: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
c230: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
c240: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
c250: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
c260: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
c270: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
c280: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
c290: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
c2a0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
c2b0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
c2c0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
c2d0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
c2e0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
c2f0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
c300: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
c310: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
c320: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
c330: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
c340: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
c350: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
c360: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
c370: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
c380: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
c390: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
c3a0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
c3b0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
c3c0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
c3d0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
c3e0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
c3f0: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
c400: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
c410: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
c420: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
c430: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
c440: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
c450: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
c460: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
c470: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
c480: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
c490: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
c4a0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
c4b0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
c4c0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
c4d0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
c4e0: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
c4f0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
c500: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
c510: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
c520: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
c530: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
c540: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
c550: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
c560: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
c570: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
c580: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
c590: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
c5a0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
c5b0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
c5c0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
c5d0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
c5e0: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
c5f0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
c600: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
c610: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
c620: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
c630: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
c640: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
c650: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
c660: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
c670: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
c680: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
c690: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
c6a0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
c6b0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
c6c0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
c6d0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
c6e0: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
c6f0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
c700: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
c710: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
c720: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
c730: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
c740: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
c750: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
c760: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
c770: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
c780: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
c790: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
c7a0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
c7b0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
c7c0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
c7d0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
c7e0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
c7f0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
c800: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
c810: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
c820: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
c830: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
c840: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
c850: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
c860: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
c870: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
c880: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
c890: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
c8a0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
c8b0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
c8c0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
c8d0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
c8e0: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
c8f0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
c900: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
c910: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
c920: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
c930: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
c940: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
c950: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
c960: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
c970: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
c980: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
c990: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
c9a0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
c9b0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
c9c0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
c9d0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
c9e0: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
c9f0: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
ca00: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
ca10: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
ca20: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
ca30: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
ca40: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
ca50: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
ca60: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
ca70: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
ca80: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
ca90: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
caa0: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
cab0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
cac0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
cad0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
cae0: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
caf0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
cb00: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
cb10: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
cb20: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
cb30: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
cb40: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
cb50: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
cb60: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
cb70: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
cb80: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
cb90: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
cba0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
cbb0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
cbc0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
cbd0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
cbe0: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
cbf0: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
cc00: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
cc10: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
cc20: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
cc30: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
cc40: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
cc50: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
cc60: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
cc70: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
cc80: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
cc90: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
cca0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
ccb0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
ccc0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
ccd0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
cce0: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
ccf0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
cd00: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
cd10: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
cd20: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
cd30: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
cd40: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
cd50: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
cd60: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
cd70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
cd80: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
cd90: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
cda0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
cdb0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
cdc0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
cdd0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
cde0: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
cdf0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
ce00: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
ce10: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
ce20: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
ce30: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
ce40: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
ce50: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
ce60: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
ce70: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
ce80: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
ce90: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
cea0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
ceb0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
cec0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
ced0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
cee0: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
cef0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cf00: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
cf10: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
cf20: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
cf30: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
cf40: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
cf50: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
cf60: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
cf70: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
cf80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
cf90: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
cfa0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
cfb0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
cfc0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
cfd0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
cfe0: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
cff0: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
d000: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
d010: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
d020: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
d030: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
d040: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
d050: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
d060: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
d070: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
d080: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
d090: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
d0a0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
d0b0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
d0c0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
d0d0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
d0e0: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
d0f0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
d100: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
d110: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
d120: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
d130: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
d140: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
d150: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
d160: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
d170: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
d180: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
d190: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
d1a0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
d1b0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
d1c0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
d1d0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
d1e0: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
d1f0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
d200: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
d210: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
d220: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
d230: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
d240: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
d250: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
d260: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
d270: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
d280: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
d290: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
d2a0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
d2b0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
d2c0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
d2d0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
d2e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
d2f0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
d300: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
d310: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
d320: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
d330: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
d340: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
d350: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
d360: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
d370: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
d380: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
d390: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
d3a0: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
d3b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
d3c0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
d3d0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
d3e0: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
d3f0: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
d400: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
d410: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
d420: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
d430: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
d440: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
d450: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
d460: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
d470: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
d480: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
d490: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
d4a0: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
d4b0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
d4c0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
d4d0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
d4e0: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
d4f0: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
d500: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
d510: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
d520: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
d530: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
d540: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
d550: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
d560: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
d570: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
d580: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
d590: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
d5a0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
d5b0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
d5c0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
d5d0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
d5e0: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
d5f0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
d600: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
d610: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
d620: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
d630: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
d640: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
d650: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
d660: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
d670: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
d680: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
d690: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
d6a0: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
d6b0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
d6c0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
d6d0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
d6e0: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
d6f0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
d700: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
d710: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
d720: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
d730: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
d740: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
d750: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
d760: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
d770: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
d780: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
d790: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d7a0: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
d7b0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
d7c0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
d7d0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
d7e0: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
d7f0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
d800: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
d810: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
d820: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
d830: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
d840: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
d850: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
d860: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
d870: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
d880: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
d890: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
d8a0: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
d8b0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
d8c0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
d8d0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
d8e0: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
d8f0: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
d900: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
d910: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
d920: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
d930: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
d940: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
d950: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
d960: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
d970: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
d980: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
d990: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
d9a0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
d9b0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
d9c0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
d9d0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
d9e0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
d9f0: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
da00: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
da10: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
da20: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
da30: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
da40: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
da50: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
da60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
da70: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
da80: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
da90: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
daa0: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
dab0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
dac0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
dad0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
dae0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
daf0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
db00: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
db10: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
db20: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
db30: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
db40: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
db50: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
db60: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
db70: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
db80: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
db90: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
dba0: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
dbb0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
dbc0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
dbd0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
dbe0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
dbf0: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
dc00: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
dc10: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
dc20: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
dc30: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
dc40: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
dc50: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
dc60: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
dc70: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
dc80: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
dc90: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
dca0: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
dcb0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
dcc0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
dcd0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
dce0: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
dcf0: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
dd00: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
dd10: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
dd20: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
dd30: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
dd40: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
dd50: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
dd60: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
dd70: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
dd80: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
dd90: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
dda0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
ddb0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
ddc0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
ddd0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
dde0: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
ddf0: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
de00: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
de10: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
de20: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
de30: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
de40: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
de50: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
de60: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
de70: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
de80: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
de90: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
dea0: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
deb0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
dec0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
ded0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
dee0: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
def0: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
df00: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
df10: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
df20: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
df30: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
df40: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
df50: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
df60: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
df70: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
df80: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
df90: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
dfa0: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
dfb0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
dfc0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
dfd0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
dfe0: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
dff0: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
e000: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
e010: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
e020: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
e030: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
e040: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
e050: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
e060: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
e070: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
e080: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
e090: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
e0a0: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
e0b0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
e0c0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
e0d0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
e0e0: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
e0f0: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
e100: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
e110: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
e120: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
e130: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
e140: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
e150: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
e160: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
e170: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
e180: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
e190: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
e1a0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
e1b0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
e1c0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
e1d0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
e1e0: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
e1f0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
e200: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
e210: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
e220: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
e230: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
e240: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
e250: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
e260: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
e270: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
e280: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
e290: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
e2a0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
e2b0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
e2c0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
e2d0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
e2e0: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
e2f0: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
e300: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
e310: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
e320: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
e330: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
e340: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
e350: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
e360: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
e370: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
e380: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
e390: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e3a0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e3b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
e3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
e3d0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
e3e0: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
e3f0: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
e400: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e410: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
e420: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
e430: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
e440: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e450: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
e460: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
e470: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
e480: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
e490: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e4a0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
e4b0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
e4c0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
e4d0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
e4e0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e4f0: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
e500: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
e510: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
e520: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
e530: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
e540: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
e550: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
e560: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
e570: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
e580: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
e590: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
e5a0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
e5b0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
e5c0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
e5d0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
e5e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
e5f0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e600: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
e610: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
e620: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
e630: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
e640: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
e650: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
e660: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
e670: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
e680: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e690: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
e6a0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
e6b0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
e6c0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
e6d0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
e6e0: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
e6f0: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
e700: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
e710: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
e720: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
e730: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
e740: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
e750: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
e760: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
e770: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
e780: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
e790: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
e7a0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
e7b0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
e7c0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
e7d0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e7e0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e7f0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
e800: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
e810: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
e820: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
e830: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
e840: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e850: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
e860: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
e870: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e880: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e890: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
e8a0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e8b0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e8c0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
e8d0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
e8e0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
e8f0: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
e900: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
e910: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
e920: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
e930: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
e940: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
e950: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
e960: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
e970: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
e980: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
e990: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
e9a0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
e9b0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
e9c0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
e9d0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
e9e0: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
e9f0: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
ea00: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
ea10: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
ea20: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
ea30: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
ea40: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
ea50: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
ea60: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
ea70: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
ea80: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ea90: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
eaa0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
eab0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
eac0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
ead0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
eae0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
eaf0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
eb00: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
eb10: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
eb20: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
eb30: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
eb40: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
eb50: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
eb60: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
eb70: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
eb80: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
eb90: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
eba0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
ebb0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
ebc0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
ebd0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
ebe0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
ebf0: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
ec00: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
ec10: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
ec20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
ec30: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
ec40: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
ec50: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
ec60: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
ec70: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
ec80: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
ec90: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
eca0: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
ecb0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
ecc0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
ecd0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
ece0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
ecf0: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
ed00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
ed10: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
ed20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
ed30: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
ed40: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
ed50: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
ed60: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
ed70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
ed80: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
ed90: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
eda0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
edb0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
edc0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
edd0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
ede0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
edf0: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
ee00: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
ee10: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
ee20: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
ee30: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
ee40: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
ee50: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
ee60: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
ee70: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
ee80: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
ee90: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
eea0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
eeb0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
eec0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
eed0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
eee0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
eef0: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
ef00: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
ef10: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
ef20: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
ef30: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
ef40: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
ef50: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
ef60: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
ef70: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
ef80: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
ef90: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
efa0: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
efb0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
efc0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
efd0: 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70  n on the corresp
efe0: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
eff0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
f000: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
f010: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
f020: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
f030: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
f040: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
f050: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
f060: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
f070: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
f080: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
f090: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
f0a0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
f0b0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
f0c0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
f0d0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
f0e0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
f0f0: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
f100: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
f110: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
f120: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
f130: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
f140: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
f150: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
f160: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
f170: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
f180: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
f190: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
f1a0: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
f1b0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
f1c0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
f1d0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
f1e0: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
f1f0: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
f200: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
f210: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
f220: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f230: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
f240: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
f250: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
f260: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
f270: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
f280: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f290: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
f2a0: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
f2b0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
f2c0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
f2d0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
f2e0: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
f2f0: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
f300: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
f310: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
f320: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
f330: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
f340: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
f350: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
f360: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
f370: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
f380: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
f390: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
f3a0: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
f3b0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
f3c0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
f3d0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
f3e0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
f3f0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
f400: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f410: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
f420: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
f430: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
f440: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
f450: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
f460: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
f470: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
f480: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
f490: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
f4a0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
f4b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
f4c0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
f4d0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
f4e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f4f0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
f500: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
f510: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
f520: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
f530: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
f540: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
f550: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
f560: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
f570: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
f580: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f590: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
f5a0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
f5b0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
f5c0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
f5d0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
f5e0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
f5f0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
f600: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
f610: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
f620: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f630: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
f640: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
f650: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
f660: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
f670: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
f680: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
f690: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f6a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f6b0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
f6c0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
f6d0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
f6e0: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
f6f0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f700: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
f710: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
f720: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
f730: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
f740: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
f750: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
f760: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
f770: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
f780: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
f790: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
f7a0: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
f7b0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
f7c0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
f7d0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
f7e0: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
f7f0: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
f800: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
f810: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
f820: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
f830: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
f840: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
f850: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
f860: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f870: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f880: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
f890: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
f8a0: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
f8b0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
f8c0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f8d0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
f8e0: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
f8f0: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
f900: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
f910: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
f920: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
f930: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
f940: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
f950: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
f960: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
f970: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
f980: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f990: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
f9a0: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
f9b0: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
f9c0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f9d0: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
f9e0: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
f9f0: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
fa00: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
fa10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fa20: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
fa30: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
fa40: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
fa50: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
fa60: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
fa70: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
fa80: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
fa90: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
faa0: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
fab0: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
fac0: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
fad0: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
fae0: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
faf0: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
fb00: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
fb10: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
fb20: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
fb30: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
fb40: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
fb50: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
fb60: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
fb70: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
fb80: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
fb90: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
fba0: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
fbb0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
fbc0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
fbd0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
fbe0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
fbf0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
fc00: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
fc10: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
fc20: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
fc30: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
fc40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fc50: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
fc60: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
fc70: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
fc80: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
fc90: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
fca0: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
fcb0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
fcc0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
fcd0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
fce0: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
fcf0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
fd00: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
fd10: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
fd20: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
fd30: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
fd40: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
fd50: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
fd60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
fd70: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
fd80: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
fd90: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
fda0: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
fdb0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
fdc0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
fdd0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
fde0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
fdf0: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
fe00: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
fe10: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
fe20: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
fe30: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
fe40: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
fe50: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
fe60: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
fe70: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
fe80: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
fe90: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
fea0: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
feb0: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
fec0: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
fed0: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
fee0: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
fef0: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
ff00: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ff10: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
ff20: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
ff30: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
ff40: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
ff50: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
ff60: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
ff70: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
ff80: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
ff90: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
ffa0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ffb0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
ffc0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
ffd0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
ffe0: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
fff0: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
10000 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
10010 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10020 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
10030 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
10040 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
10050 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
10060 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
10070 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
10080 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
10090 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
100a0 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
100b0 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
100c0 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
100d0 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
100e0 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
100f0 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
10100 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
10110 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
10120 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
10130 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
10140 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
10150 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
10160 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
10170 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
10180 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
10190 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
101a0 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
101b0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
101c0 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
101d0 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
101e0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
101f0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
10200 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
10210 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
10220 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
10230 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
10240 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
10250 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
10260 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ilure..*/.SQLITE
10270 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
10280 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
10290 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
102a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
102b0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
102c0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
102d0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
102e0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
102f0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 73  DCALL sqlite3_os
10300 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c  _init(void);.SQL
10310 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
10320 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
10330 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
10340 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10350 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
10360 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
10370 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
10380 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
10390 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
103a0 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
103b0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
103c0 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
103d0 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
103e0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
103f0 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
10400 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
10410 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
10420 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
10430 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
10440 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
10450 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
10460 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
10470 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
10480 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
10490 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
104a0 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
104b0 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
104c0 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
104d0 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  <b>The sqlite3_c
104e0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
104f0 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
10500 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61  afe. The applica
10510 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
10520 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
10530 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
10540 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
10550 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
10560 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
10570 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
10580 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a  nning.</b>.**.**
10590 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
105a0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a  fig() interface.
105b0 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
105c0 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
105d0 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
105e0 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
105f0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
10600 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
10610 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
10620 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10630 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
10640 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
10650 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
10660 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
10670 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
10680 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10690 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
106a0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
106b0 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
106c0 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
106d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
106e0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
106f0 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
10700 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
10710 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
10720 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
10730 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
10740 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
10750 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
10760 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
10770 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e   integer.** [con
10780 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10790 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
107a0 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
107b0 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
107c0 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
107d0 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
107e0 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
107f0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
10800 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e [configuration
10810 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
10820 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10830 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
10840 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10850 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
10860 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
10870 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
10880 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
10890 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
108a0 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
108b0 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
108c0 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
108d0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
108e0 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
108f0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
10900 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
10910 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69  QLITE_CDECL sqli
10920 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
10930 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
10940 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
10950 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
10960 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
10970 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
10980 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
10990 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
109a0 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
109b0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
109c0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
109d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
109e0 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
109f0 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
10a00 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
10a10 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
10a20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
10a30 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
10a40 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
10a50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
10a60 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
10a70 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
10a80 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
10a90 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
10aa0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
10ab0 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
10ac0 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
10ad0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
10ae0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
10af0 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
10b00 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
10b10 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
10b20 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
10b30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10b40 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
10b50 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
10b60 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
10b70 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
10b80 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
10b90 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
10ba0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
10bb0 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
10bc0 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
10bd0 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
10be0 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
10bf0 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
10c00 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
10c10 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c  int SQLITE_CDECL
10c20 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
10c30 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
10c40 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
10c50 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
10c60 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
10c70 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
10c80 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10c90 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
10ca0 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
10cb0 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
10cc0 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
10cd0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10ce0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
10cf0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
10d00 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
10d10 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
10d20 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
10d30 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
10d40 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10d50 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
10d60 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10d70 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10d80 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
10d90 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10da0 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
10db0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
10dc0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
10dd0 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
10de0 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
10df0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10e00 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
10e10 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
10e20 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
10e30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10e40 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
10e50 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
10e60 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
10e70 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
10e80 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
10e90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
10ea0 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
10eb0 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
10ec0 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
10ed0 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
10ee0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
10ef0 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
10f00 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
10f10 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
10f20 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
10f30 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
10f40 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
10f50 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
10f60 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
10f70 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
10f80 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
10f90 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
10fa0 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
10fb0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
10fc0 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
10fd0 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
10fe0 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
10ff0 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
11000 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
11010 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
11020 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
11030 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
11040 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
11050 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11060 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
11070 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
11080 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
11090 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
110a0 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
110b0 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
110c0 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
110d0 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
110e0 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
110f0 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
11100 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
11110 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
11120 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
11130 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
11140 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
11150 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
11160 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
11170 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
11180 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
11190 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
111a0 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
111b0 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
111c0 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
111d0 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
111e0 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
111f0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
11200 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
11210 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
11220 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
11230 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
11240 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
11250 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
11260 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
11270 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
11280 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
11290 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
112a0 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
112b0 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
112c0 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
112d0 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
112e0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
112f0 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
11300 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
11310 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
11320 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
11330 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
11340 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
11350 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
11360 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
11370 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
11380 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
11390 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
113a0 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
113b0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
113c0 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
113d0 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
113e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
113f0 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
11400 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
11410 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
11420 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
11430 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
11440 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
11450 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
11460 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
11470 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
11480 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
11490 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
114a0 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
114b0 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
114c0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
114d0 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70  ator.  For examp
114e0 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
114f0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
11500 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
11510 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
11520 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
11530 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
11540 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
11550 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
11560 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
11570 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
11580 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
11590 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
115a0 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
115b0 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
115c0 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
115d0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
115e0 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
115f0 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
11600 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
11610 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
11620 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
11630 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
11640 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
11650 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
11660 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
11670 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
11680 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
11690 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
116a0 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
116b0 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
116c0 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
116d0 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
116e0 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
116f0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
11700 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
11710 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
11720 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
11730 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
11740 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
11750 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
11760 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
11770 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
11780 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11790 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
117a0 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
117b0 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
117c0 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
117d0 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
117e0 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
117f0 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
11800 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11810 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
11820 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
11830 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
11840 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
11850 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
11860 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
11870 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
11880 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
11890 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
118a0 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
118b0 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
118c0 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
118d0 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
118e0 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
118f0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
11900 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11910 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
11920 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
11930 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11940 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
11950 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
11960 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
11970 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
11980 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
11990 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
119a0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
119b0 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
119c0 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
119d0 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
119e0 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
119f0 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
11a00 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
11a10 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
11a20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
11a30 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
11a40 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
11a50 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
11a60 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
11a70 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
11a80 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
11a90 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
11aa0 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
11ab0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
11ac0 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
11ad0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11ae0 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
11af0 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
11b00 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
11b10 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
11b20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
11b30 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
11b40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
11b50 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
11b60 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
11b70 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
11b80 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
11b90 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
11ba0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
11bb0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11bc0 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion}.**.** Thes
11bd0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
11be0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
11bf0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
11c00 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
11c10 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
11c20 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
11c30 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
11c40 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11c50 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
11c60 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
11c70 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
11c80 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
11c90 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
11ca0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
11cb0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
11cc0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
11cd0 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
11ce0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
11cf0 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
11d00 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
11d10 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
11d20 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
11d30 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
11d40 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
11d50 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
11d60 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
11d70 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
11d80 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
11d90 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
11da0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
11db0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
11dc0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
11dd0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
11de0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
11df0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
11e00 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
11e10 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11e20 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
11e30 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
11e40 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
11e50 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
11e60 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
11e70 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
11e80 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
11e90 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
11ea0 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
11eb0 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
11ec0 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
11ed0 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
11ee0 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
11ef0 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
11f00 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
11f10 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
11f20 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11f30 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
11f40 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11f50 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11f60 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11f70 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
11f80 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
11f90 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
11fa0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
11fb0 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
11fc0 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
11fd0 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
11fe0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11ff0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
12000 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
12010 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
12020 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
12030 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
12040 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
12050 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
12060 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12070 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
12080 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12090 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
120a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
120b0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
120c0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
120d0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
120e0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
120f0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
12100 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
12110 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
12120 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
12130 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
12140 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12150 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
12160 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
12170 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
12180 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
12190 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
121a0 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
121b0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
121c0 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
121d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
121e0 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
121f0 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
12200 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
12210 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
12220 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
12230 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
12240 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
12250 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
12260 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
12270 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
12280 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12290 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
122a0 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
122b0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
122c0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
122d0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
122e0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
122f0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12300 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12310 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
12320 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
12330 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
12340 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
12350 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
12360 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
12370 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12380 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
12390 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
123a0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
123b0 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
123c0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
123d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
123e0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
123f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12400 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
12410 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
12420 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
12430 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12440 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
12450 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12460 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12470 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
12480 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
12490 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
124a0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
124b0 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
124c0 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
124d0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
124e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
124f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12500 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
12510 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
12520 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
12530 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
12540 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
12550 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
12560 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
12570 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
12580 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
12590 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
125a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
125b0 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
125c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
125d0 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
125e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
125f0 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
12600 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
12610 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
12620 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
12630 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
12640 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
12650 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
12660 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
12670 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
12680 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
12690 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
126a0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
126b0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
126c0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
126d0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
126e0 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
126f0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
12700 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
12710 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12720 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
12730 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
12740 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
12750 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
12760 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
12770 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12780 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
12790 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
127a0 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
127b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
127c0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
127d0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
127e0 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e  IG_MALLOC option
127f0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12800 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12810 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
12820 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
12830 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12840 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12850 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
12860 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
12870 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
12880 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
12890 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
128a0 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
128b0 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
128c0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
128d0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
128e0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
128f0 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
12900 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
12910 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
12920 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
12930 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12940 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
12950 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
12960 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12970 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
12980 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12990 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
129a0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
129b0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
129c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
129d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
129e0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69  G_GETMALLOC opti
129f0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12a00 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12a10 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
12a20 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
12a30 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12a40 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
12a50 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b  ucture..** The [
12a60 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12a70 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
12a80 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
12a90 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
12aa0 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
12ab0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12ac0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
12ad0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
12ae0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
12af0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
12b00 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
12b10 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
12b20 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
12b30 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
12b40 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
12b50 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
12b60 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
12b70 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
12b80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12b90 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20  FIG_MEMSTATUS]] 
12ba0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12bb0 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
12bc0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
12bd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
12be0 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b  TATUS option tak
12bf0 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
12c00 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a  nt of type int,.
12c10 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ** interpreted a
12c20 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  s a boolean, whi
12c30 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
12c40 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
12c50 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f  ction of.** memo
12c60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
12c70 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
12c80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12c90 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
12ca0 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74  e.** disabled, t
12cb0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
12cc0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
12cd0 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
12ce0 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
12cf0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
12d00 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
12d10 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
12d20 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
12d30 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
12d40 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
12d50 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
12d60 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
12d70 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d  ite3_status64()]
12d80 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
12d90 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
12da0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
12db0 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
12dc0 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
12dd0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
12de0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
12df0 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
12e00 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
12e10 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
12e20 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
12e30 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
12e40 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
12e50 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12e60 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12e70 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
12e80 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
12e90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
12ea0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
12eb0 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70  CRATCH option sp
12ec0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
12ed0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a   memory buffer.*
12ee0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  * that SQLite ca
12ef0 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63  n use for scratc
12f00 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65  h memory.  ^(The
12f10 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
12f20 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c  uments.** to SQL
12f30 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12f40 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  CH:  A pointer a
12f50 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
12f60 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
12f70 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
12f80 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12f90 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
12fa0 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
12fb0 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
12fc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
12fd0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
12fe0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
12ff0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
13000 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20  s (N).)^.** The 
13010 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
13020 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72  ust be a pointer
13030 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
13040 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20  igned buffer.** 
13050 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
13060 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
13070 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
13080 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74  l not use more t
13090 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20  han one scratch 
130a0 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65  buffers per thre
130b0 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ad..** ^SQLite w
130c0 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73  ill never reques
130d0 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  t a scratch buff
130e0 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
130f0 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20  than 6.** times 
13100 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
13110 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53  e size..** ^If S
13120 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
13130 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
13140 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
13150 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
13160 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
13170 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13180 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
13190 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
131a0 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
131b0 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
131c0 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a  ry needed.<p>.**
131d0 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69   ^When the appli
131e0 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20  cation provides 
131f0 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63  any amount of sc
13200 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69  ratch memory usi
13210 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  ng.** SQLITE_CON
13220 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c  FIG_SCRATCH, SQL
13230 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63  ite avoids unnec
13240 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20  essary large.** 
13250 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c  [sqlite3_malloc|
13260 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  heap allocations
13270 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68  ]..** This can h
13280 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f  elp [Robson proo
13290 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79  f|prevent memory
132a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
132b0 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61  ures] due to hea
132c0 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69  p.** fragmentati
132d0 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79  on in low-memory
132e0 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
132f0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
13300 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13310 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
13320 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13330 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
13340 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
13350 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13360 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  CHE option speci
13370 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
13380 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74  mory buffer.** t
13390 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
133a0 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  se for the datab
133b0 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
133c0 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
133d0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
133e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
133f0 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
13400 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
13410 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
13420 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
13430 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
13440 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
13450 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
13460 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
13470 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20 63 6f  G_PCACHE2].** co
13480 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13490 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  on..** ^There ar
134a0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
134b0 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
134c0 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20  IG_PAGECACHE: A 
134d0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d  pointer to.** 8-
134e0 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
134f0 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
13500 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
13510 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
13520 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
13530 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
13540 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
13550 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
13560 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
13570 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
13580 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
13590 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35  tween 512 and 65
135a0 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65  536) plus some e
135b0 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65  xtra bytes for e
135c0 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
135d0 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72  er.  ^The number
135e0 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20   of extra bytes 
135f0 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61  needed by the pa
13600 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e  ge header.** can
13610 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
13620 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
13630 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
13640 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a  DRSZ] option .**
13650 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
13660 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69  fig()]..** ^It i
13670 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
13680 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
13690 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72  d memory,.** for
136a0 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65   the sz paramete
136b0 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74  r to be larger t
136c0 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20  han necessary.  
136d0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
136e0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
136f0 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
13700 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20  e aligned block 
13710 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74 0a 2a  of memory that.*
13720 2a 20 69 73 20 61 74 20 6c 65 61 73 74 20 73 7a  * is at least sz
13730 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
13740 72 79 2c 20 6f 74 68 65 72 77 69 73 65 20 73 75  ry, otherwise su
13750 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
13760 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
13770 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  d..** ^SQLite wi
13780 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
13790 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
137a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
137b0 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
137c0 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
137d0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
137e0 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
137f0 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
13800 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
13810 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
13820 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
13830 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
13840 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
13850 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
13860 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
13870 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
13880 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
13890 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 3c   storage space.<
138a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
138b0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
138c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
138d0 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
138e0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
138f0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70  E_CONFIG_HEAP op
13900 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
13910 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
13920 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53  uffer .** that S
13930 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66  QLite will use f
13940 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
13950 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
13960 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a  ocation needs.**
13970 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
13980 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53  ovided for by [S
13990 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
139a0 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51  ATCH] and.** [SQ
139b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
139c0 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20  CACHE]..** ^The 
139d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
139e0 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  AP option is onl
139f0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53  y available if S
13a00 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13a10 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72  d.** with either
13a20 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
13a30 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c  MEMSYS3] or [SQL
13a40 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
13a50 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  S5] and returns.
13a60 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
13a70 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68  ] if invoked oth
13a80 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72  erwise..** ^Ther
13a90 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
13aa0 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
13ab0 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20  CONFIG_HEAP:.** 
13ac0 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
13ad0 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
13ae0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
13af0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
13b00 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
13b10 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
13b20 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
13b30 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
13b40 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
13b50 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
13b60 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
13b70 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
13b80 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
13b90 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
13ba0 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
13bb0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
13bc0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
13bd0 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
13be0 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
13bf0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
13c00 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
13c10 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
13c20 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
13c30 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  LL then the alte
13c40 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
13c50 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
13c60 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
13c70 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
13c80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13c90 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
13ca0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
13cb0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
13cc0 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
13cd0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
13ce0 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
13cf0 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
13d00 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
13d10 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a  l be undefined..
13d20 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61  ** The minimum a
13d30 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69  llocation size i
13d40 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31  s capped at 2**1
13d50 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61  2. Reasonable va
13d60 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  lues.** for the 
13d70 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
13d80 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35  on size are 2**5
13d90 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f   through 2**8.</
13da0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13db0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
13dc0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13dd0 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
13de0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
13df0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
13e00 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13e10 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13e20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f  which is a.** po
13e30 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
13e40 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
13e50 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13e60 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
13e70 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
13e80 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61  pecifies alterna
13e90 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
13ea0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
13eb0 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70   be used.** in p
13ec0 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72  lace the mutex r
13ed0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
13ee0 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
13ef0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
13f00 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
13f10 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
13f20 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13f30 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
13f40 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
13f50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13f60 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
13f70 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13f80 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13f90 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13fa0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13fb0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13fc0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13fd0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
13fe0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
13ff0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
14000 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
14010 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
14020 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
14030 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
14040 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14050 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
14060 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
14070 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
14080 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
14090 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
140a0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
140b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
140c0 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
140d0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
140e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
140f0 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
14100 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14110 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
14120 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14130 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
14140 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
14150 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
14160 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
14170 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
14180 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
14190 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
141a0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
141b0 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
141c0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
141d0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
141e0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
141f0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
14200 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
14210 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
14220 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
14230 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
14240 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
14250 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
14260 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
14270 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
14280 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
14290 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
142a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
142b0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
142c0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
142d0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
142e0 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
142f0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
14300 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
14310 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
14320 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
14330 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
14340 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
14350 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
14360 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
14370 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
14380 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
14390 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
143a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
143b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
143c0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
143d0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
143e0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
143f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
14400 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SIDE option take
14410 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
14420 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a  that determine.*
14430 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69  * the default si
14440 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20  ze of lookaside 
14450 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b  memory on each [
14460 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14470 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ion]..** The fir
14480 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
14490 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
144a0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
144b0 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
144c0 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
144d0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
144e0 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
144f0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
14500 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51  nection.)^  ^(SQ
14510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14520 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68  ASIDE.** sets th
14530 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  e <i>default</i>
14540 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
14550 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
14560 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
14570 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73  .** option to [s
14580 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
14590 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20  ()] can be used 
145a0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
145b0 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69  okaside.** confi
145c0 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  guration on indi
145d0 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f  vidual connectio
145e0 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ns.)^ </dd>.**.*
145f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14600 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  G_PCACHE2]] <dt>
14610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14620 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
14630 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14640 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
14650 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14660 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
14670 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
14680 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69  nter to an [sqli
14690 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
146a0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ds2] object.  Th
146b0 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
146c0 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72  ies.** the inter
146d0 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d  face to a custom
146e0 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
146f0 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  ementation.)^.**
14700 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
14710 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
14720 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14730 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f  hods2] object.</
14740 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14750 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14760 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
14770 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
14780 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
14790 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
147a0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
147b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
147c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
147d0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
147e0 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69  nter to an [sqli
147f0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
14800 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ds2] object.  SQ
14810 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a  Lite copies of.*
14820 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61  * the current pa
14830 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
14840 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
14850 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64  t object.)^ </dd
14860 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14870 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64  _CONFIG_LOG]] <d
14880 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14890 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
148a0 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   The SQLITE_CONF
148b0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73  IG_LOG option is
148c0 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
148d0 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a  re the SQLite.**
148e0 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c   global [error l
148f0 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51  og]..** (^The SQ
14900 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
14910 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
14920 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
14930 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
14940 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
14950 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
14960 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
14970 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
14980 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
14990 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
149a0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
149b0 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
149c0 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
149d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
149e0 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
149f0 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
14a00 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
14a10 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
14a20 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
14a30 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
14a40 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
14a50 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
14a60 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
14a70 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
14a80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
14a90 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
14aa0 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
14ab0 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
14ac0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
14ad0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
14ae0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
14af0 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
14b00 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
14b10 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
14b20 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
14b30 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
14b40 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
14b50 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
14b60 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
14b70 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
14b80 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
14b90 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
14ba0 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
14bb0 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
14bc0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
14bd0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
14be0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
14bf0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
14c00 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
14c10 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
14c20 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
14c30 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
14c40 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
14c50 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
14c60 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
14c70 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
14c80 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
14c90 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
14ca0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
14cb0 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
14cc0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
14cd0 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
14ce0 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
14cf0 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
14d00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
14d10 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
14d20 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
14d30 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
14d40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14d50 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51  FIG_URI]] <dt>SQ
14d60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a  LITE_CONFIG_URI.
14d70 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c  ** <dd>^(The SQL
14d80 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f  ITE_CONFIG_URI o
14d90 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14da0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
14db0 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66   type int..** If
14dc0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
14dd0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
14de0 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
14df0 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
14e00 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74  er is zero,.** t
14e10 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
14e20 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
14e30 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49  abled.)^ ^If URI
14e40 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
14e50 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64  bally.** enabled
14e60 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20  , all filenames 
14e70 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
14e80 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
14e90 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
14ea0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
14eb0 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65  n16()] or.** spe
14ec0 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
14ed0 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61  f [ATTACH] comma
14ee0 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  nds are interpre
14ef0 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67  ted as URIs, reg
14f00 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68  ardless.** of wh
14f10 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
14f20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
14f30 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  I] flag is set w
14f40 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
14f50 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
14f60 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74  s opened. ^If it
14f70 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
14f80 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73  abled, filenames
14f90 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74   are.** only int
14fa0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
14fb0 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f   if the SQLITE_O
14fc0 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20  PEN_URI flag is 
14fd0 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  set when the.** 
14fe0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14ff0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
15000 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49  (By default, URI
15010 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
15020 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
15030 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
15040 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
15050 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
15060 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
15070 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
15080 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a  mbol defined.)^.
15090 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
150a0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
150b0 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e  NDEX_SCAN]] <dt>
150c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
150d0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
150e0 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  N.** <dd>^The SQ
150f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15100 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
15110 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15120 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a  ingle integer.**
15130 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
15140 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
15150 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f  s a boolean in o
15160 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f  rder to enable o
15170 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  r disable.** the
15180 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
15190 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
151a0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e  l table scans in
151b0 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d   the query optim
151c0 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  izer..** ^The de
151d0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73  fault setting is
151e0 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62   determined.** b
151f0 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c  y the [SQLITE_AL
15200 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  LOW_COVERING_IND
15210 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65  EX_SCAN] compile
15220 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72  -time option, or
15230 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74   is "on".** if t
15240 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  hat compile-time
15250 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74   option is omitt
15260 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69  ed..** The abili
15270 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68  ty to disable th
15280 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
15290 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
152a0 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a  ll table scans.*
152b0 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d  * is because som
152c0 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f  e incorrectly co
152d0 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69  ded legacy appli
152e0 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61  cations might ma
152f0 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65  lfunction.** whe
15300 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  n the optimizati
15310 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20  on is enabled.  
15320 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62  Providing the ab
15330 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61  ility to.** disa
15340 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  ble the optimiza
15350 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20  tion allows the 
15360 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70  older, buggy app
15370 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f  lication code to
15380 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74   work.** without
15390 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74   change even wit
153a0 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  h newer versions
153b0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
153c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
153d0 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
153e0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
153f0 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
15400 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15410 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
15420 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a  NFIG_GETPCACHE.*
15430 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74  * <dd> These opt
15440 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74  ions are obsolet
15450 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74  e and should not
15460 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20   be used by new 
15470 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72  code..** They ar
15480 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
15490 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
154a0 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e  bility but are n
154b0 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f  ow no-ops..** </
154c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
154d0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
154e0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
154f0 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a  _CONFIG_SQLLOG.*
15500 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
15510 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
15520 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73  ble if sqlite is
15530 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
15540 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
15550 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65  ABLE_SQLLOG] pre
15560 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
15570 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
15580 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
15590 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
155a0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
155b0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
155c0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
155d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
155e0 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
155f0 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
15600 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
15610 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
15620 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
15630 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
15640 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
15650 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
15660 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
15670 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
15680 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15690 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
156a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
156b0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
156c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
156d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
156e0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
156f0 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
15700 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
15710 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
15720 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
15730 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
15740 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
15750 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
15760 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
15770 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
15780 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
15790 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
157a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
157b0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
157c0 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
157d0 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
157e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
157f0 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
15800 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
15810 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
15820 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15830 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
15840 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
15850 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
15860 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
15870 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c  case.  An exampl
15880 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a  e of using this.
15890 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
158a0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73   option can be s
158b0 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74  een in the "test
158c0 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63  _sqllog.c" sourc
158d0 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65  e file in.** the
158e0 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74   canonical SQLit
158f0 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f  e source tree.</
15900 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15910 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
15920 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
15930 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
15940 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c  SIZE.** <dd>^SQL
15950 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
15960 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36  SIZE takes two 6
15970 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73  4-bit integer (s
15980 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61  qlite3_int64) va
15990 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  lues.** that are
159a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61   the default mma
159b0 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68  p size limit (th
159c0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
159d0 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41  g for.** [PRAGMA
159e0 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64   mmap_size]) and
159f0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c   the maximum all
15a00 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c  owed mmap size l
15a10 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  imit..** ^The de
15a20 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61  fault setting ca
15a30 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20  n be overridden 
15a40 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65  by each database
15a50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e   connection usin
15a60 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20  g.** either the 
15a70 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
15a80 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62  e] command, or b
15a90 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  y using the.** [
15aa0 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
15ab0 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
15ac0 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78  trol.  ^(The max
15ad0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
15ae0 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62  p size.** will b
15af0 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  e silently trunc
15b00 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72  ated if necessar
15b10 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65  y so that it doe
15b20 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65  s not exceed the
15b30 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
15b40 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69   maximum mmap si
15b50 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a  ze set by the.**
15b60 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41   [SQLITE_MAX_MMA
15b70 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d  P_SIZE] compile-
15b80 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a  time option.)^.*
15b90 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67  * ^If either arg
15ba0 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70  ument to this op
15bb0 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65  tion is negative
15bc0 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75  , then that argu
15bd0 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67  ment is.** chang
15be0 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c  ed to its compil
15bf0 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a  e-time default..
15c00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15c10 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
15c20 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
15c30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15c40 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64  2_HEAPSIZE.** <d
15c50 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
15c60 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15c70 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  IZE option is on
15c80 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
15c90 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
15ca0 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77  piled for Window
15cb0 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  s with the [SQLI
15cc0 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d  TE_WIN32_MALLOC]
15cd0 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
15ce0 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e  acro.** defined.
15cf0 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   ^SQLITE_CONFIG_
15d00 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74  WIN32_HEAPSIZE t
15d10 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e  akes a 32-bit un
15d20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76  signed integer v
15d30 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65  alue.** that spe
15d40 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d  cifies the maxim
15d50 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63  um size of the c
15d60 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a  reated heap..**.
15d70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15d80 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d  IG_PCACHE_HDRSZ]
15d90 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
15da0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
15db0 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  RSZ.** <dd>^The 
15dc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15dd0 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f  ACHE_HDRSZ optio
15de0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15df0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
15e00 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
15e10 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61   to an integer a
15e20 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74  nd writes into t
15e30 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20  hat integer the 
15e40 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a  number of extra.
15e50 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67  ** bytes per pag
15e60 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65  e required for e
15e70 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c  ach page in [SQL
15e80 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
15e90 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d  ACHE]..** The am
15ea0 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70  ount of extra sp
15eb0 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e  ace required can
15ec0 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e   change dependin
15ed0 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  g on the compile
15ee0 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61  r,.** target pla
15ef0 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74  tform, and SQLit
15f00 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  e version..**.**
15f10 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15f20 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _PMASZ]].** <dt>
15f30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
15f40 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ASZ.** <dd>^The 
15f50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
15f60 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  ASZ option takes
15f70 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
15f80 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
15f90 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  an unsigned inte
15fa0 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65  ger and sets the
15fb0 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69   "Minimum PMA Si
15fc0 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74  ze" for the mult
15fd0 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72  ithreaded.** sor
15fe0 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65  ter to that inte
15ff0 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ger.  The defaul
16000 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69  t minimum PMA Si
16010 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65  ze is set by the
16020 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54  .** [SQLITE_SORT
16030 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c  ER_PMASZ] compil
16040 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20  e-time option.  
16050 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20  New threads are 
16060 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68  launched.** to h
16070 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70  elp with sort op
16080 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75  erations when mu
16090 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74  ltithreaded sort
160a0 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65  ing.** is enable
160b0 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52  d (using the [PR
160c0 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f  AGMA threads] co
160d0 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61  mmand) and the a
160e0 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74  mount of content
160f0 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64  .** to be sorted
16100 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67   exceeds the pag
16110 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65  e size times the
16120 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a   minimum of the.
16130 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65  ** [PRAGMA cache
16140 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61  _size] setting a
16150 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a  nd this value..*
16160 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
16170 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16180 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
16190 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
161a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
161b0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
161c0 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
161d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
161e0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
161f0 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
16200 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16210 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
16220 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
16230 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
16240 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16250 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
16260 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
16270 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
16280 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16290 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
162a0 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
162b0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
162c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
162d0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
162e0 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
162f0 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
16300 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
16310 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
16320 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
16330 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
16340 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
16350 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16360 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
16370 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
16380 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16390 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
163a0 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
163b0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
163c0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
163d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
163e0 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
163f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
16400 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
16410 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
16420 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
16430 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
16440 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
16450 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16460 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
16470 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
16480 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16490 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
164a0 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f       14  /* no-o
164b0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
164c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
164d0 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e  ACHE    15  /* n
164e0 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
164f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16500 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
16510 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
16520 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16530 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20  _CONFIG_URI     
16540 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20       17  /* int 
16550 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16560 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
16570 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c        18  /* sql
16580 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
16590 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
165a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
165b0 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20  ETPCACHE2   19  
165c0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
165d0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
165e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
165f0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
16600 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20  DEX_SCAN 20  /* 
16610 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16620 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
16630 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a  LOG       21  /*
16640 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20   xSqllog, void* 
16650 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16660 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
16670 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c  ZE    22  /* sql
16680 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69  ite3_int64, sqli
16690 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65  te3_int64 */.#de
166a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
166b0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
166c0 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e  E      23  /* in
166d0 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69  t nByte */.#defi
166e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
166f0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20  _PCACHE_HDRSZ   
16700 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20       24  /* int 
16710 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  *psz */.#define 
16720 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
16730 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20  ASZ             
16740 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65    25  /* unsigne
16750 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a  d int szPma */..
16760 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16770 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
16780 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
16790 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
167a0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
167b0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
167c0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
167d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
167e0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
167f0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
16800 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
16810 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
16820 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
16830 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
16840 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16850 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
16860 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
16870 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
16880 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
16890 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
168a0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
168b0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
168c0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
168d0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
168e0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
168f0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
16900 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
16910 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
16920 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
16930 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
16940 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
16950 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
16960 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
16970 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
16980 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
16990 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
169a0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
169b0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
169c0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
169d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
169e0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
169f0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
16a00 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
16a10 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
16a20 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
16a30 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
16a40 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
16a50 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
16a60 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
16a70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
16a80 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
16a90 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
16aa0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
16ab0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
16ac0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
16ad0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
16ae0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
16af0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
16b00 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
16b10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
16b20 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
16b30 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
16b40 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
16b50 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
16b60 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
16b70 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
16b80 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
16b90 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
16ba0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16bb0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
16bc0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
16bd0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
16be0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
16bf0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
16c00 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
16c10 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
16c20 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
16c30 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
16c40 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
16c50 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
16c60 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
16c70 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
16c80 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
16c90 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
16ca0 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
16cb0 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
16cc0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
16cd0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
16ce0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
16cf0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
16d00 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
16d10 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
16d20 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
16d30 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
16d40 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
16d50 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
16d60 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
16d70 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
16d80 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
16d90 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
16da0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16db0 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
16dc0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
16dd0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
16de0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
16df0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
16e00 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
16e10 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
16e20 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
16e30 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
16e40 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
16e50 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
16e60 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
16e70 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
16e80 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
16e90 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
16ea0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
16eb0 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
16ec0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
16ed0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
16ee0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
16ef0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
16f00 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
16f10 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
16f20 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
16f30 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
16f40 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
16f50 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
16f60 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
16f70 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
16f80 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
16f90 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
16fa0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
16fb0 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
16fc0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
16fd0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
16fe0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
16ff0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
17000 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
17010 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
17020 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
17030 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
17040 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
17050 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
17060 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
17070 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
17080 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
17090 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
170a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
170b0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
170c0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
170d0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
170e0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
170f0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
17100 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
17110 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
17120 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17130 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
17140 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
17150 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
17160 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
17170 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
17180 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
17190 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
171a0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
171b0 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
171c0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
171d0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
171e0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
171f0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
17200 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
17210 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
17220 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
17230 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
17240 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
17250 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
17260 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
17270 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
17280 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
17290 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
172a0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
172b0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
172c0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
172d0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
172e0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
172f0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
17300 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
17310 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
17320 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
17330 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
17340 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
17350 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
17360 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
17370 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17380 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
17390 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
173a0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
173b0 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
173c0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
173d0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
173e0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
173f0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
17400 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
17410 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
17420 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
17430 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
17440 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
17450 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74      1002  /* int
17460 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
17470 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
17480 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
17490 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e   1003  /* int in
174a0 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
174b0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
174c0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
174d0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
174e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
174f0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
17500 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
17510 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
17520 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
17530 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
17540 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
17550 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
17560 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
17570 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
17580 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
17590 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
175a0 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
175b0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
175c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
175d0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
175e0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
175f0 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
17600 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
17610 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
17620 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
17630 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f  t Rowid.** METHO
17640 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
17650 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
17660 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c  most SQLite tabl
17670 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b  es (except for [
17680 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
17690 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20  ables).** has a 
176a0 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
176b0 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
176c0 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
176d0 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
176e0 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
176f0 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
17700 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
17710 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
17720 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
17730 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
17740 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
17750 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
17760 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
17770 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
17780 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
17790 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
177a0 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
177b0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
177c0 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
177d0 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
177e0 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
177f0 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  wid..**.** ^The 
17800 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
17810 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74  ert_rowid(D) int
17820 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
17830 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
17840 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  e .** most recen
17850 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  t successful [IN
17860 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77  SERT] into a row
17870 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72  id table or [vir
17880 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f  tual table].** o
17890 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
178a0 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73  ction D..** ^Ins
178b0 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
178c0 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
178d0 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65   are not recorde
178e0 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63  d..** ^If no suc
178f0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
17900 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
17910 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  les.** have ever
17920 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65   occurred on the
17930 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17940 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e  tion D, .** then
17950 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
17960 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65  sert_rowid(D) re
17970 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
17980 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
17990 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
179a0 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69   a trigger or wi
179b0 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20  thin a [virtual 
179c0 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64  table].** method
179d0 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  , then this rout
179e0 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ine will return 
179f0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
17a00 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
17a10 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ow as long as th
17a20 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
17a30 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
17a40 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  d is running..**
17a50 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
17a60 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
17a70 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e   table method en
17a80 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
17a90 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
17aa0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
17ab0 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
17ac0 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
17ad0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a  gger or virtual.
17ae0 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  ** table method 
17af0 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  began.)^.**.** ^
17b00 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74  An [INSERT] that
17b10 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
17b20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
17b30 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
17b40 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
17b50 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f  ERT] and does no
17b60 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
17b70 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
17b80 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
17b90 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52   ^Thus INSERT OR
17ba0 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
17bb0 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
17bc0 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
17bd0 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
17be0 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
17bf0 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
17c00 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
17c10 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
17c20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
17c30 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49  fails.  ^(When I
17c40 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
17c50 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
17c60 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
17c70 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
17c80 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
17c90 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
17ca0 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
17cb0 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
17cc0 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
17cd0 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
17ce0 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
17cf0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
17d00 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
17d10 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
17d20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
17d30 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  terface.)^.**.**
17d40 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
17d50 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
17d60 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
17d70 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
17d80 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
17d90 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
17da0 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
17db0 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
17dc0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
17dd0 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
17de0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
17df0 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
17e00 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
17e10 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
17e20 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
17e30 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
17e40 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
17e50 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  on the same.** d
17e60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17e70 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
17e80 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17e90 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75  t_rowid()].** fu
17ea0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
17eb0 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
17ec0 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
17ed0 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74  rt [rowid],.** t
17ee0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
17ef0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
17f00 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
17f10 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e  owid()] is.** un
17f20 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
17f30 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
17f40 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
17f50 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73  r the new.** las
17f60 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
17f70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
17f80 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51  sqlite3_int64 SQ
17f90 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
17fa0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
17fb0 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
17fc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17fd0 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
17fe0 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
17ff0 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
18000 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
18010 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
18020 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
18030 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
18040 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a  , inserted or.**
18050 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
18060 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
18070 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
18080 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
18090 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e  .** statement on
180a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
180b0 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69  nnection specifi
180c0 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70  ed by the only p
180d0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78  arameter..** ^Ex
180e0 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
180f0 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
18100 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
18110 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75   modify the valu
18120 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
18130 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
18140 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e  **.** ^Only chan
18150 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c  ges made directl
18160 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c  y by the INSERT,
18170 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
18180 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a  E statement are.
18190 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20  ** considered - 
181a0 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  auxiliary change
181b0 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45  s caused by [CRE
181c0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
181d0 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f  iggers], .** [fo
181e0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
181f0 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20  s] or [REPLACE] 
18200 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
18210 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f  ution are not co
18220 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68  unted..** .** Ch
18230 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
18240 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
18250 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53  pted by .** [INS
18260 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
18270 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  | INSTEAD OF tri
18280 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63  ggers] are not c
18290 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c  ounted. ^The val
182a0 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ue .** returned 
182b0 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
182c0 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79  es() immediately
182d0 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54   after an INSERT
182e0 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20  , UPDATE or .** 
182f0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
18300 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69   run on a view i
18310 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f  s always zero. O
18320 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
18330 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62   to real .** tab
18340 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  les are counted.
18350 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72  .**.** Things ar
18360 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74  e more complicat
18370 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65  ed if the sqlite
18380 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
18390 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75  tion is.** execu
183a0 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67  ted while a trig
183b0 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72  ger program is r
183c0 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79  unning. This may
183d0 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a   happen if the.*
183e0 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74  * program uses t
183f0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
18400 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20  L function], or 
18410 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61  if some other ca
18420 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
18430 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74  on invokes sqlit
18440 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72  e3_changes() dir
18450 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c  ectly. Essential
18460 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a  ly:.** .** <ul>.
18470 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f  **   <li> ^(Befo
18480 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72  re entering a tr
18490 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68  igger program th
184a0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
184b0 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71   by.**        sq
184c0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
184d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65  function is save
184e0 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69  d. After the tri
184f0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a  gger program .**
18500 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69          has fini
18510 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e  shed, the origin
18520 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74  al value is rest
18530 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20  ored.)^.** .**  
18540 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61   <li> ^(Within a
18550 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
18560 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50   each INSERT, UP
18570 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20  DATE and DELETE 
18580 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65  .**        state
18590 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61  ment sets the va
185a0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
185b0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
185c0 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f  ) .**        upo
185d0 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20  n completion as 
185e0 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73  normal. Of cours
185f0 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69  e, this value wi
18600 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a  ll not include .
18610 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68  **        any ch
18620 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20  anges performed 
18630 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c  by sub-triggers,
18640 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f   as the sqlite3_
18650 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
18660 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20       value will 
18670 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73  be saved and res
18680 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68  tored after each
18690 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73   sub-trigger has
186a0 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e   run.)^.** </ul>
186b0 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65  .** .** ^This me
186c0 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20  ans that if the 
186d0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
186e0 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c  nction (or simil
186f0 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62  ar) is used.** b
18700 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45  y the first INSE
18710 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
18720 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
18730 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
18740 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20   it .** returns 
18750 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74  the value as set
18760 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e   when the callin
18770 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61  g statement bega
18780 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  n executing..** 
18790 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62  ^If it is used b
187a0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20  y the second or 
187b0 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20  subsequent such 
187c0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
187d0 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70   a trigger .** p
187e0 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75  rogram, the valu
187f0 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65  e returned refle
18800 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  cts the number o
18810 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20  f rows modified 
18820 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69  by the .** previ
18830 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ous INSERT, UPDA
18840 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
18850 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
18860 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
18870 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
18880 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
18890 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
188a0 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
188b0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
188c0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
188d0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
188e0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
188f0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
18900 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
18910 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
18920 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18930 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
18940 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
18950 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
18960 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
18970 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
18980 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
18990 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c  aningful..*/.SQL
189a0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
189b0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
189c0 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
189d0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
189e0 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
189f0 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
18a00 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
18a10 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
18a20 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
18a30 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e  urns the total n
18a40 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
18a50 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64  serted, modified
18a60 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
18a70 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20  y all [INSERT], 
18a80 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
18a90 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
18aa0 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e  completed.** sin
18ab0 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ce the database 
18ac0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f  connection was o
18ad0 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67  pened, including
18ae0 20 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20   those executed 
18af0 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72  as.** part of tr
18b00 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20  igger programs. 
18b10 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
18b20 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
18b30 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f   statement.** do
18b40 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68  es not affect th
18b50 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
18b60 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
18b70 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20  l_changes()..** 
18b80 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64  .** ^Changes mad
18b90 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f  e as part of [fo
18ba0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
18bb0 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20  s] are included 
18bc0 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c  in the.** count,
18bd0 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20   but those made 
18be0 61 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41  as part of REPLA
18bf0 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  CE constraint re
18c00 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20  solution are.** 
18c10 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f  not. ^Changes to
18c20 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
18c30 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
18c40 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
18c50 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ers .** are not 
18c60 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
18c70 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
18c80 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
18c90 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
18ca0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
18cb0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
18cc0 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65  he [total_change
18cd0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
18ce0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
18cf0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
18d00 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
18d10 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
18d20 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
18d30 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
18d40 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
18d50 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
18d60 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
18d70 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
18d80 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
18d90 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c  aningful..*/.SQL
18da0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
18db0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
18dc0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
18dd0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
18de0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
18df0 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
18e00 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d  nning Query.** M
18e10 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
18e20 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
18e30 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
18e40 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
18e50 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
18e60 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
18e70 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
18e80 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
18e90 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
18ea0 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
18eb0 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
18ec0 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
18ed0 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
18ee0 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
18ef0 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
18f00 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
18f10 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
18f20 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
18f30 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
18f40 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
18f50 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
18f60 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
18f70 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
18f80 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
18f90 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
18fa0 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
18fb0 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
18fc0 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
18fd0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
18fe0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
18ff0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
19000 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
19010 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
19020 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
19030 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19040 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
19050 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
19060 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
19070 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
19080 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
19090 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
190a0 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
190b0 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
190c0 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
190d0 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
190e0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
190f0 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
19100 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
19110 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
19120 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
19130 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
19140 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
19150 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
19160 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
19170 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
19180 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
19190 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
191a0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
191b0 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
191c0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
191d0 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
191e0 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
191f0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
19200 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
19210 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19220 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
19230 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
19240 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
19250 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
19260 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
19270 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19280 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
19290 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
192a0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
192b0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
192c0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
192d0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
192e0 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
192f0 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
19300 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
19310 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
19320 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
19330 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
19340 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
19350 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
19360 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
19370 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
19380 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
19390 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
193a0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
193b0 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
193c0 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
193d0 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
193e0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
193f0 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
19400 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
19410 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
19420 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
19430 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
19440 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
19450 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
19460 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
19470 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
19480 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
19490 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
194a0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
194b0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
194c0 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
194d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
194e0 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
194f0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
19500 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
19510 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
19520 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
19530 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
19540 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44   void SQLITE_STD
19550 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 69 6e 74  CALL sqlite3_int
19560 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
19570 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19580 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
19590 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
195a0 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
195b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
195c0 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
195d0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
195e0 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
195f0 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
19600 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
19610 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
19620 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
19630 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
19640 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
19650 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
19660 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
19670 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
19680 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
19690 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
196a0 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
196b0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
196c0 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
196d0 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
196e0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
196f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
19700 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
19710 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
19720 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
19730 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
19740 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
19750 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
19760 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
19770 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
19780 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
19790 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
197a0 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
197b0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
197c0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
197d0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
197e0 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
197f0 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
19800 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
19810 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
19820 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
19830 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
19840 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
19850 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
19860 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
19870 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
19880 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
19890 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
198a0 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
198b0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
198c0 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
198d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
198e0 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
198f0 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
19900 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
19910 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
19920 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
19930 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
19940 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
19950 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
19960 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
19970 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
19980 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
19990 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
199a0 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
199b0 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
199c0 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
199d0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
199e0 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
199f0 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
19a00 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
19a10 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
19a20 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
19a30 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
19a40 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
19a50 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
19a60 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
19a70 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
19a80 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
19a90 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
19aa0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
19ab0 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
19ac0 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
19ad0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
19ae0 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
19af0 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
19b00 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
19b10 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
19b20 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
19b30 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
19b40 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
19b50 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
19b60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
19b70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
19b80 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
19b90 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
19ba0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
19bb0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51  yte order..*/.SQ
19bc0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
19bd0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
19be0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
19bf0 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53  st char *sql);.S
19c00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
19c10 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
19c20 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
19c30 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
19c40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19c50 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
19c60 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
19c70 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
19c80 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ors.** KEYWORDS:
19c90 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63   {busy-handler c
19ca0 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68  allback} {busy h
19cb0 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  andler}.** METHO
19cc0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19cd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75   ^The sqlite3_bu
19ce0 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50  sy_handler(D,X,P
19cf0 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  ) routine sets a
19d00 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
19d10 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67  on X.** that mig
19d20 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
19d30 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
19d40 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
19d50 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
19d60 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
19d70 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74  e table associat
19d80 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61  ed with.** [data
19d90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19da0 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20   D when another 
19db0 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
19dc0 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62  cess has the tab
19dd0 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68  le locked..** Th
19de0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
19df0 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61  andler() interfa
19e00 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d  ce is used to im
19e10 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69  plement.** [sqli
19e20 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
19e30 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  ()] and [PRAGMA 
19e40 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a  busy_timeout]..*
19e50 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
19e60 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
19e70 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
19e80 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74  _BUSY].** is ret
19e90 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
19ea0 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
19eb0 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
19ec0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
19ed0 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
19ee0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
19ef0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
19f00 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
19f10 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
19f20 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
19f30 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
19f40 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
19f50 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
19f60 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
19f70 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
19f80 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
19f90 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
19fa0 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
19fb0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
19fc0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
19fd0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
19fe0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
19ff0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
1a000 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
1a010 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f  n invoked previo
1a020 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d  usly for the sam
1a030 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
1a040 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
1a050 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
1a060 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
1a070 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
1a080 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
1a090 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1a0a0 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
1a0b0 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e  _BUSY] is return
1a0c0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  ed.** to the app
1a0d0 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  lication..** ^If
1a0e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1a0f0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1a100 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
1a110 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
1a120 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1a130 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63  tabase and the c
1a140 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
1a150 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
1a160 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
1a170 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
1a180 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
1a190 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1a1a0 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
1a1b0 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
1a1c0 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
1a1d0 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
1a1e0 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
1a1f0 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
1a200 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
1a210 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
1a220 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
1a230 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1a240 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1a250 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ion instead of i
1a260 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20  nvoking the .** 
1a270 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1a280 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
1a290 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
1a2a0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1a2b0 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
1a2c0 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
1a2d0 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
1a2e0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1a2f0 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
1a300 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1a310 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
1a320 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
1a330 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
1a340 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
1a350 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
1a360 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
1a370 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
1a380 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1a390 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
1a3a0 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
1a3b0 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
1a3c0 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
1a3d0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1a3e0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
1a3f0 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
1a400 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
1a410 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
1a420 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
1a430 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
1a440 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
1a450 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
1a460 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
1a470 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1a480 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
1a490 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
1a4a0 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
1a4b0 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
1a4c0 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
1a4d0 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
1a4e0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
1a4f0 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
1a500 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
1a510 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1a520 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  LL..**.** ^(Ther
1a530 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1a540 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1a550 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1a560 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1a570 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1a580 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1a590 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1a5a0 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1a5b0 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1a5c0 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1a5d0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1a5e0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1a5f0 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ** or evaluating
1a600 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1a610 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68  meout=N] will ch
1a620 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79  ange the.** busy
1a630 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75   handler and thu
1a640 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76  s clear any prev
1a650 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20  iously set busy 
1a660 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
1a670 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1a680 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
1a690 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
1a6a0 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
1a6b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a6c0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1a6d0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1a6e0 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  er.  In other wo
1a6f0 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79  rds,.** the busy
1a700 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20   handler is not 
1a710 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20  reentrant.  Any 
1a720 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1a730 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1a740 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1a750 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1a760 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1a770 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1a780 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1a790 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1a7a0 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1a7b0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1a7c0 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ler..*/.SQLITE_A
1a7d0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
1a7e0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75  DCALL sqlite3_bu
1a7f0 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
1a800 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
1a810 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
1a820 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a830 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
1a840 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  out.** METHOD: s
1a850 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1a860 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
1a870 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
1a880 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
1a890 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
1a8a0 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
1a8b0 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
1a8c0 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
1a8d0 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
1a8e0 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
1a8f0 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
1a900 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
1a910 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1a920 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1a930 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
1a940 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
1a950 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
1a960 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1a970 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
1a980 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
1a990 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
1a9a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1a9b0 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
1a9c0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
1a9d0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
1a9e0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
1a9f0 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
1aa00 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
1aa10 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
1aa20 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
1aa30 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lers..**.** ^(Th
1aa40 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1aa50 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1aa60 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
1aa70 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1aa80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1aa90 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  at any given mom
1aaa0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
1aab0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
1aac0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
1aad0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
1aae0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
1aaf0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
1ab00 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
1ab10 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
1ab20 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
1ab30 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  red.)^.**.** See
1ab40 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20   also:  [PRAGMA 
1ab50 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f  busy_timeout].*/
1ab60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1ab70 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1ab80 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1ab90 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
1aba0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
1abb0 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
1abc0 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
1abd0 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
1abe0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1abf0 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te3.**.** This i
1ac00 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
1ac10 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
1ac20 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
1ac30 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1ac40 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
1ac50 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1ac60 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
1ac70 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
1ac80 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
1ac90 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
1aca0 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
1acb0 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
1acc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1acd0 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
1ace0 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
1acf0 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
1ad00 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
1ad10 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
1ad20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
1ad30 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
1ad40 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
1ad50 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
1ad60 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
1ad70 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
1ad80 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
1ad90 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
1ada0 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
1adb0 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
1adc0 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
1add0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
1ade0 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
1adf0 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
1ae00 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
1ae10 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
1ae20 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1ae30 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
1ae40 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
1ae50 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1ae60 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
1ae70 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
1ae80 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
1ae90 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
1aea0 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
1aeb0 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
1aec0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1aed0 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
1aee0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
1aef0 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
1af00 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
1af10 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
1af20 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
1af30 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
1af40 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
1af50 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
1af60 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
1af70 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
1af80 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1af90 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
1afa0 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
1afb0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
1afc0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
1afd0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1afe0 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
1aff0 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1b000 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1b010 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1b020 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1b030 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1b040 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1b050 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1b060 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1b070 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1b080 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1b090 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1b0a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1b0b0 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1b0c0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1b0d0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1b0e0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1b0f0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1b100 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1b110 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1b120 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1b130 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1b140 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1b150 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1b160 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1b170 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1b180 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1b190 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1b1a0 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1b1b0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1b1c0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1b1d0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1b1e0 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1b1f0 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1b200 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1b210 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1b220 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1b230 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1b240 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1b250 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1b260 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1b270 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1b280 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1b290 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1b2a0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1b2b0 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1b2c0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b2d0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1b2e0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1b2f0 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1b300 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1b310 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1b320 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1b330 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1b340 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1b350 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1b360 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1b370 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b380 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1b390 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b3a0 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1b3b0 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1b3c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1b3d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b3e0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1b3f0 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1b400 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1b410 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1b420 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1b430 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1b440 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1b450 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1b460 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1b470 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1b480 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1b490 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1b4a0 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1b4b0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1b4c0 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1b4d0 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1b4e0 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1b4f0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1b500 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1b510 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1b520 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1b530 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1b540 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1b550 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1b560 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1b570 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1b580 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1b590 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1b5a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1b5b0 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1b5c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1b5d0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1b5e0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1b5f0 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1b600 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1b610 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1b620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1b630 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1b640 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1b650 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1b660 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1b670 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1b680 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1b690 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1b6a0 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1b6b0 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1b6c0 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1b6d0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1b6e0 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1b6f0 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1b700 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1b710 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1b720 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1b730 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1b740 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1b750 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1b760 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1b770 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1b780 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1b790 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1b7a0 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1b7b0 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1b7c0 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1b7d0 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1b7e0 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1b7f0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1b800 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1b810 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1b820 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  rrmsg()]..*/.SQL
1b830 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
1b840 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1b850 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1b860 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1b870 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1b880 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1b890 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1b8a0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1b8b0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1b8c0 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1b8d0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1b8e0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1b8f0 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1b900 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1b910 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1b920 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1b930 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1b940 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1b950 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1b960 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1b970 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1b980 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1b990 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1b9a0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53  ten here */.);.S
1b9b0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53  QLITE_API void S
1b9c0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1b9d0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1b9e0 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
1b9f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ba00 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
1ba10 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
1ba20 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1ba30 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
1ba40 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
1ba50 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
1ba60 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
1ba70 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
1ba80 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1ba90 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1baa0 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f  es understand mo
1bab0 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e  st of the common
1bac0 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20   K&R formatting 
1bad0 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73  options,.** plus
1bae0 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1baf0 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f   non-standard fo
1bb00 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20  rmats, detailed 
1bb10 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74  below..** Note t
1bb20 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20  hat some of the 
1bb30 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72  more obscure for
1bb40 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
1bb50 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43  from recent.** C
1bb60 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61 72  -library standar
1bb70 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66  ds are omitted f
1bb80 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65  rom this impleme
1bb90 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ntation..**.** ^
1bba0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
1bbb0 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
1bbc0 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
1bbd0 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
1bbe0 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
1bbf0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
1bc00 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
1bc10 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
1bc20 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
1bc30 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
1bc40 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
1bc50 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
1bc60 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
1bc70 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
1bc80 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
1bc90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
1bca0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1bcb0 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
1bcc0 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
1bcd0 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
1bce0 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
1bcf0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
1bd00 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  The sqlite3_snpr
1bd10 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1bd20 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
1bd30 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
1bd40 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
1bd50 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
1bd60 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
1bd70 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
1bd80 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
1bd90 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1bda0 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
1bdb0 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
1bdc0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1bdd0 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
1bde0 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
1bdf0 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
1be00 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
1be10 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
1be20 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61  ().)^  This is a
1be30 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
1be40 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
1be50 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
1be60 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
1be70 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
1be80 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f  atibility.  ^(No
1be90 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
1bea0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1beb0 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
1bec0 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
1bed0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1bee0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
1bef0 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
1bf00 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
1bf10 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57  the buffer.)^  W
1bf20 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
1bf30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
1bf40 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
1bf50 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
1bf60 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
1bf70 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
1bf80 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
1bf90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1bfa0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1bfb0 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
1bfc0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
1bfd0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
1bfe0 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74  ** ^As long as t
1bff0 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
1c000 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
1c010 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
1c020 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
1c030 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
1c040 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
1c050 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
1c060 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20    ^The first.** 
1c070 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
1c080 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
1c090 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
1c0a0 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
1c0b0 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
1c0c0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
1c0d0 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
1c0e0 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
1c0f0 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
1c100 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
1c110 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
1c120 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1c130 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1c140 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20  ne is a varargs 
1c150 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74  version of sqlit
1c160 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a  e3_snprintf()..*
1c170 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1c180 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  nes all implemen
1c190 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  t some additiona
1c1a0 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20  l formatting.** 
1c1b0 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  options that are
1c1c0 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73   useful for cons
1c1d0 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61  tructing SQL sta
1c1e0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20  tements..** All 
1c1f0 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69  of the usual pri
1c200 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67  ntf() formatting
1c210 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20   options apply. 
1c220 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68   In addition, th
1c230 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25  ere.** is are "%
1c240 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61  q", "%Q", "%w" a
1c250 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
1c260 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
1c270 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1c280 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
1c290 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
1c2a0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
1c2b0 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
1c2c0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
1c2d0 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
1c2e0 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
1c2f0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
1c300 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
1c310 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
1c320 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
1c330 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
1c340 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
1c350 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
1c360 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
1c370 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
1c380 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
1c390 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
1c3a0 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1c3b0 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
1c3c0 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
1c3d0 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
1c3e0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1c3f0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1c400 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
1c410 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
1c420 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
1c430 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1c440 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
1c450 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
1c460 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1c470 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1c480 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1c490 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1c4a0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1c4b0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1c4c0 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1c4d0 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
1c4e0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1c4f0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1c500 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1c510 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1c520 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1c530 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
1c540 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
1c550 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
1c560 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
1c570 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
1c580 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
1c590 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
1c5a0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1c5b0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1c5c0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1c5d0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1c5e0 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
1c5f0 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
1c600 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1c610 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
1c620 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
1c630 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
1c640 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
1c650 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
1c660 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
1c670 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1c680 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1c690 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1c6a0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1c6b0 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
1c6c0 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
1c6d0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1c6e0 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
1c6f0 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
1c700 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
1c710 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
1c720 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
1c730 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
1c740 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
1c750 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
1c760 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
1c770 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
1c780 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
1c790 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
1c7a0 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
1c7b0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
1c7c0 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
1c7d0 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
1c7e0 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
1c7f0 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
1c800 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
1c810 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
1c820 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1c830 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
1c840 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
1c850 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
1c860 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
1c870 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
1c880 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
1c890 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1c8a0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1c8b0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1c8c0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1c8d0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1c8e0 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
1c8f0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1c900 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1c910 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1c920 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1c930 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1c940 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1c950 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
1c960 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
1c970 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1c980 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
1c990 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
1c9a0 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
1c9b0 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
1c9c0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
1c9d0 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e  e "%w" formattin
1c9e0 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65  g option is like
1c9f0 20 22 25 71 22 20 65 78 63 65 70 74 20 74 68 61   "%q" except tha
1ca00 74 20 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a  t it expects to.
1ca10 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  ** be contained 
1ca20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75  within double-qu
1ca30 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20  otes instead of 
1ca40 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61  single quotes, a
1ca50 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73  nd it.** escapes
1ca60 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74   the double-quot
1ca70 65 20 63 68 61 72 61 63 74 65 72 20 69 6e 73 74  e character inst
1ca80 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c  ead of the singl
1ca90 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61  e-quote.** chara
1caa0 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77  cter.)^  The "%w
1cab0 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1cac0 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ion is intended 
1cad0 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72  for safely inser
1cae0 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e  ting.** table an
1caf0 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69  d column names i
1cb00 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65  nto a constructe
1cb10 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  d SQL statement.
1cb20 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a  .**.** ^(The "%z
1cb30 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1cb40 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22  ion works like "
1cb50 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65  %s" but with the
1cb60 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
1cb70 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
1cb80 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
1cb90 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
1cba0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
1cbb0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1cbc0 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
1cbd0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29  e input string.)
1cbe0 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ^.*/.SQLITE_API 
1cbf0 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 43 44 45  char *SQLITE_CDE
1cc00 43 4c 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  CL sqlite3_mprin
1cc10 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1cc20 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
1cc30 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
1cc40 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 6d 70  CALL sqlite3_vmp
1cc50 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1cc60 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c  *, va_list);.SQL
1cc70 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51  ITE_API char *SQ
1cc80 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74  LITE_CDECL sqlit
1cc90 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
1cca0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1ccb0 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  *, ...);.SQLITE_
1ccc0 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45  API char *SQLITE
1ccd0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1cce0 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
1ccf0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1cd00 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
1cd10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1cd20 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
1cd30 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
1cd40 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
1cd50 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
1cd60 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
1cd70 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
1cd80 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
1cd90 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
1cda0 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
1cdb0 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
1cdc0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
1cdd0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
1cde0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
1cdf0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1ce00 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
1ce10 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
1ce20 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
1ce30 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
1ce40 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
1ce50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1ce60 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
1ce70 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1ce80 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
1ce90 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
1cea0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
1ceb0 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
1cec0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1ced0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
1cee0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
1cef0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
1cf00 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
1cf10 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
1cf20 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1cf30 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
1cf40 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
1cf50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1cf60 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
1cf70 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
1cf80 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
1cf90 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1cfa0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
1cfb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e  lite3_malloc64(N
1cfc0 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20  ) routine works 
1cfd0 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c  just like.** sql
1cfe0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65  ite3_malloc(N) e
1cff0 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20  xcept that N is 
1d000 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62  an unsigned 64-b
1d010 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  it integer inste
1d020 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65  ad.** of a signe
1d030 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72  d 32-bit integer
1d040 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1d050 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1d060 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
1d070 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
1d080 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1d090 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1d0a0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1d0b0 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
1d0c0 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
1d0d0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
1d0e0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1d0f0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
1d100 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
1d110 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1d120 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1d130 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
1d140 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
1d150 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1d160 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
1d170 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
1d180 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
1d190 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
1d1a0 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
1d1b0 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
1d1c0 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
1d1d0 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
1d1e0 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
1d1f0 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
1d200 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
1d210 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
1d220 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
1d230 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
1d240 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1d250 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
1d260 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
1d270 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
1d280 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
1d290 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
1d2a0 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
1d2b0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1d2c0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1d2d0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
1d2e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1d2f0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65  ealloc(X,N) inte
1d300 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
1d310 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
1d320 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
1d330 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74  ation X to be at
1d340 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a   least N bytes..
1d350 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72  ** ^If the X par
1d360 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1d370 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a  3_realloc(X,N).*
1d380 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
1d390 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
1d3a0 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
1d3b0 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
1d3c0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d3d0 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  N)..** ^If the N
1d3e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1d3f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1d400 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  N) is zero or.**
1d410 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1d420 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1d430 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1d440 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1d450 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a  lite3_free(X)..*
1d460 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
1d470 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1d480 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
1d490 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d4a0 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
1d4b0 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
1d4c0 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66  or NULL if insuf
1d4d0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
1d4e0 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
1d4f0 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
1d500 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
1d510 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
1d520 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
1d530 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
1d540 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
1d550 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
1d560 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
1d570 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
1d580 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d590 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72  (X,N) and the pr
1d5a0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1d5b0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1d5c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d5d0 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  X,N) returns NUL
1d5e0 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74  L and N is posit
1d5f0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ive, then the.**
1d600 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1d610 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  n is not freed..
1d620 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1d630 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e  e3_realloc64(X,N
1d640 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72  ) interfaces wor
1d650 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  ks the same as.*
1d660 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  * sqlite3_reallo
1d670 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68  c(X,N) except th
1d680 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74  at N is a 64-bit
1d690 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
1d6a0 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
1d6b0 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  a 32-bit signed 
1d6c0 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  integer..**.** ^
1d6d0 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79  If X is a memory
1d6e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76   allocation prev
1d6f0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
1d700 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1d710 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
1d720 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71  3_malloc64(), sq
1d730 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1d740 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1d750 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a  loc64(), then.**
1d760 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1d770 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  ) returns the si
1d780 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72  ze of that memor
1d790 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20  y allocation in 
1d7a0 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76  bytes..** ^The v
1d7b0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1d7c0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1d7d0 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65  ) might be large
1d7e0 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65  r than the numbe
1d7f0 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65  r.** of bytes re
1d800 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77  quested when X w
1d810 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e  as allocated.  ^
1d820 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70  If X is a NULL p
1d830 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73  ointer then.** s
1d840 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1d850 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49  returns zero.  I
1d860 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f  f X points to so
1d870 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20  mething that is 
1d880 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e  not.** the begin
1d890 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ning of memory a
1d8a0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66  llocation, or if
1d8b0 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20   it points to a 
1d8c0 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69  formerly.** vali
1d8d0 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
1d8e0 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77  ion that has now
1d8f0 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65   been freed, the
1d900 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
1d910 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69  * of sqlite3_msi
1d920 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e  ze(X) is undefin
1d930 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20  ed and possibly 
1d940 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
1d950 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1d960 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1d970 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33  alloc(), sqlite3
1d980 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  _realloc(),.** s
1d990 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1d9a0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
1d9b0 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73  ealloc64().** is
1d9c0 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
1d9d0 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
1d9e0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20   byte boundary, 
1d9f0 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74  or to a.** 4 byt
1da00 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68  e boundary if th
1da10 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45  e [SQLITE_4_BYTE
1da20 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d  _ALIGNED_MALLOC]
1da30 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
1da40 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
1da50 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
1da60 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
1da70 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
1da80 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
1da90 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
1daa0 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
1dab0 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
1dac0 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
1dad0 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
1dae0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
1daf0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
1db00 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
1db10 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
1db20 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
1db30 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
1db40 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1db50 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
1db60 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ed..**.** Prior 
1db70 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
1db80 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69  n 3.7.10, the Wi
1db90 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
1dba0 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a  ce layer called.
1dbb0 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
1dbc0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1dbd0 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
1dbe0 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
1dbf0 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
1dc00 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
1dc10 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
1dc20 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
1dc30 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
1dc40 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
1dc50 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
1dc60 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
1dc70 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
1dc80 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
1dc90 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20   were detected, 
1dca0 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65  but.** they were
1dcb0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
1dcc0 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
1dcd0 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
1dce0 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
1dcf0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
1dd00 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
1dd10 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
1dd20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1dd30 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1dd40 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1dd50 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
1dd60 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
1dd70 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
1dd80 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
1dd90 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1dda0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
1ddb0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1ddc0 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
1ddd0 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
1dde0 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
1ddf0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1de00 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
1de10 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
1de20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
1de30 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
1de40 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
1de50 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
1de60 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
1de70 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1de80 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1de90 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  PI void *SQLITE_
1dea0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1deb0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c  malloc(int);.SQL
1dec0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51  ITE_API void *SQ
1ded0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1dee0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71  ite3_malloc64(sq
1def0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53  lite3_uint64);.S
1df00 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
1df10 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1df20 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
1df30 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  oid*, int);.SQLI
1df40 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c  TE_API void *SQL
1df50 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1df60 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f  te3_realloc64(vo
1df70 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
1df80 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
1df90 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44   void SQLITE_STD
1dfa0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 65  CALL sqlite3_fre
1dfb0 65 28 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  e(void*);.SQLITE
1dfc0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 75 69 6e  _API sqlite3_uin
1dfd0 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41  t64 SQLITE_STDCA
1dfe0 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  LL sqlite3_msize
1dff0 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1e000 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1e010 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1e020 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1e030 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1e040 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1e050 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1e060 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1e070 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1e080 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1e090 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1e0a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1e0b0 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1e0c0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1e0d0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1e0e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1e0f0 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1e100 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1e110 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1e120 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1e130 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1e140 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1e150 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1e160 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1e170 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1e180 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1e190 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1e1a0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1e1b0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1e1c0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1e1d0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1e1e0 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1e1f0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1e200 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1e210 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1e220 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1e230 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1e240 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1e250 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1e260 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1e270 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1e280 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1e290 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1e2a0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1e2b0 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1e2c0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1e2d0 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1e2e0 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1e2f0 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1e300 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1e310 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1e320 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1e330 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1e340 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1e350 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1e360 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1e370 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1e380 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1e390 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1e3a0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1e3b0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1e3c0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1e3d0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1e3e0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1e3f0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1e400 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1e410 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1e420 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1e430 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1e440 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51  sqlite3_int64 SQ
1e450 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1e460 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1e470 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
1e480 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
1e490 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1e4a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1e4b0 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
1e4c0 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
1e4d0 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
1e4e0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
1e4f0 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
1e500 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
1e510 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
1e520 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
1e530 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
1e540 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
1e550 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
1e560 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
1e570 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
1e580 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
1e590 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
1e5a0 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
1e5b0 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
1e5c0 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
1e5d0 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
1e5e0 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
1e5f0 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
1e600 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
1e610 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
1e620 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1e630 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
1e640 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
1e650 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
1e660 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
1e670 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
1e680 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
1e690 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
1e6a0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
1e6b0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68  buffer P..** ^Th
1e6c0 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61  e P parameter ca
1e6d0 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n be a NULL poin
1e6e0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ter..**.** ^If t
1e6f0 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20  his routine has 
1e700 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75  not been previou
1e710 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66  sly called or if
1e720 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a   the previous.**
1e730 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73   call had N less
1e740 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e   than one or a N
1e750 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
1e760 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47  P, then the PRNG
1e770 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73   is.** seeded us
1e780 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
1e790 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65  btained from the
1e7a0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
1e7b0 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65  hod of.** the de
1e7c0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1e7d0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
1e7e0 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  If the previous 
1e7f0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
1e800 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66  tine had an N of
1e810 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61   1 or more and a
1e820 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74  .** non-NULL P t
1e830 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72  hen the pseudo-r
1e840 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
1e850 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
1e860 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
1e870 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
1e880 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
1e890 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
1e8a0 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  thod..*/.SQLITE_
1e8b0 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f  API void SQLITE_
1e8c0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1e8d0 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
1e8e0 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
1e8f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1e900 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
1e910 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
1e920 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
1e930 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1e940 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
1e950 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  rs an authorizer
1e960 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
1e970 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1e980 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e990 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
1e9a0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
1e9b0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
1e9c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e9d0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
1e9e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
1e9f0 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
1ea00 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1ea10 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1ea20 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
1ea30 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ea40 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1ea50 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
1ea60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ea70 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
1ea80 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
1ea90 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
1eaa0 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
1eab0 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
1eac0 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
1ead0 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
1eae0 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
1eaf0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1eb00 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
1eb10 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
1eb20 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
1eb30 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
1eb40 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1eb50 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
1eb60 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
1eb70 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
1eb80 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
1eb90 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
1eba0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
1ebb0 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
1ebc0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1ebd0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
1ebe0 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
1ebf0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1ec00 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
1ec10 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
1ec20 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
1ec30 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
1ec40 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
1ec50 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ec60 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
1ec70 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
1ec80 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1ec90 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
1eca0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
1ecb0 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
1ecc0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ecd0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1ece0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1ecf0 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
1ed00 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1ed10 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1ed20 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
1ed30 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1ed40 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1ed50 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
1ed60 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
1ed70 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
1ed80 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
1ed90 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1eda0 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
1edb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1edc0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1edd0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1ede0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
1edf0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
1ee00 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1ee10 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
1ee20 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
1ee30 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
1ee40 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
1ee50 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1ee60 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1ee70 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
1ee80 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
1ee90 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
1eea0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
1eeb0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
1eec0 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
1eed0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
1eee0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1eef0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1ef00 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1ef10 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
1ef20 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
1ef30 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
1ef40 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1ef50 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
1ef60 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
1ef70 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
1ef80 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
1ef90 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1efa0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
1efb0 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
1efc0 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
1efd0 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
1efe0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
1eff0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
1f000 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1f010 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
1f020 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1f030 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
1f040 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
1f050 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1f060 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
1f070 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
1f080 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
1f090 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
1f0a0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
1f0b0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
1f0c0 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
1f0d0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
1f0e0 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
1f0f0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1f100 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
1f110 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
1f120 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
1f130 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
1f140 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
1f150 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
1f160 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
1f170 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1f180 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
1f190 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
1f1a0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1f1b0 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
1f1c0 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
1f1d0 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
1f1e0 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
1f1f0 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
1f200 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
1f210 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
1f220 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
1f230 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
1f240 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
1f250 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
1f260 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1f270 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
1f280 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
1f290 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
1f2a0 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
1f2b0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
1f2c0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
1f2d0 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
1f2e0 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
1f2f0 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
1f300 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
1f310 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
1f320 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
1f330 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
1f340 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
1f350 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
1f360 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
1f370 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
1f380 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
1f390 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
1f3a0 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
1f3b0 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
1f3c0 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
1f3d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1f3e0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
1f3f0 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
1f400 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
1f410 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
1f420 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1f430 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
1f440 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
1f450 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
1f460 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
1f470 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
1f480 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1f490 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
1f4a0 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
1f4b0 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
1f4c0 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
1f4d0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
1f4e0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1f4f0 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
1f500 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
1f510 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
1f520 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
1f530 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
1f540 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
1f550 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1f560 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
1f570 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
1f580 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
1f590 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1f5a0 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
1f5b0 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
1f5c0 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
1f5d0 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
1f5e0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
1f5f0 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
1f600 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
1f610 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
1f620 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
1f630 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
1f640 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
1f650 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
1f660 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
1f670 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
1f680 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
1f690 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
1f6a0 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
1f6b0 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
1f6c0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
1f6d0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1f6e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1f6f0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1f700 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1f710 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1f720 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1f730 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
1f740 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f750 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
1f760 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f770 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1f780 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1f790 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1f7a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f7b0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1f7c0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1f7d0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1f7e0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
1f7f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f800 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
1f810 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
1f820 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
1f830 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
1f840 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
1f850 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
1f860 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
1f870 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
1f880 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
1f890 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
1f8a0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1f8b0 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
1f8c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1f8d0 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
1f8e0 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
1f8f0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1f900 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
1f910 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1f920 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1f930 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
1f940 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f950 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1f960 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
1f970 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
1f980 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
1f990 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
1f9a0 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
1f9b0 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
1f9c0 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
1f9d0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
1f9e0 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
1f9f0 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
1fa00 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
1fa10 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
1fa20 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1fa30 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
1fa40 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54  change..*/.SQLIT
1fa50 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
1fa60 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1fa70 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1fa80 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
1fa90 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
1faa0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
1fab0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1fac0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1fad0 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
1fae0 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
1faf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1fb00 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
1fb10 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1fb20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1fb30 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1fb40 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
1fb50 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
1fb60 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
1fb70 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
1fb80 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
1fb90 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
1fba0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
1fbb0 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
1fbc0 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
1fbd0 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
1fbe0 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1fbf0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1fc00 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
1fc10 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1fc20 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1fc30 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1fc40 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
1fc50 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
1fc60 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e  o used as a [con
1fc70 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e  flict resolution
1fc80 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e   mode].** return
1fc90 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  ed from the [sql
1fca0 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
1fcb0 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61  flict()] interfa
1fcc0 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
1fcd0 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
1fce0 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
1fcf0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
1fd00 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
1fd10 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
1fd20 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
1fd30 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
1fd40 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
1fd50 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
1fd60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1fd70 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
1fd80 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1fd90 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1fda0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
1fdb0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
1fdc0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1fdd0 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
1fde0 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
1fdf0 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
1fe00 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
1fe10 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
1fe20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1fe30 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1fe40 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
1fe50 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1fe60 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
1fe70 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
1fe80 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
1fe90 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
1fea0 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
1feb0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fec0 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
1fed0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
1fee0 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
1fef0 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
1ff00 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
1ff10 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
1ff20 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
1ff30 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
1ff40 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
1ff50 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
1ff60 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1ff70 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
1ff80 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
1ff90 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
1ffa0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
1ffb0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
1ffc0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
1ffd0 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
1ffe0 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
1fff0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20000 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
20010 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
20020 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
20030 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
20040 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
20050 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
20060 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
20070 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
20080 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
20090 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
200a0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
200b0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
200c0 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
200d0 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
200e0 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
200f0 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
20100 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
20110 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
20120 2a 2f 0a 2f 2a 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 20  *************** 
20150 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
20160 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
20170 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20180 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
20190 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
201a0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
201b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
201c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
201d0 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
201e0 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
201f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
20200 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20210 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
20220 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
20230 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
20240 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
20250 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
20260 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
20270 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
20280 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
20290 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
202a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
202b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
202c0 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
202d0 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
202e0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
202f0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
20300 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
20310 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
20320 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
20330 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
20340 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20350 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
20360 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
20370 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
20380 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
20390 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
203a0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
203b0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
203c0 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
203d0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
203e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
203f0 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
20400 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
20410 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
20420 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
20430 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20440 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
20450 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
20460 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
20470 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
20480 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20490 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
204a0 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
204b0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
204c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
204d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
204e0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
204f0 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
20500 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
20510 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
20520 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20530 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
20540 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
20550 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20560 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20570 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20580 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
20590 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
205a0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
205b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
205c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
205d0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
205e0 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
205f0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
20600 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20610 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20620 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
20630 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
20640 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
20650 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
20660 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20670 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
20680 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
20690 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
206a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
206b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
206c0 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
206d0 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
206e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
206f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20700 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
20710 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
20720 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
20730 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
20740 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
20750 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
20760 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
20770 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
20780 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
20790 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
207a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
207b0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
207c0 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
207d0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
207e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
207f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
20800 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
20810 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
20820 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
20830 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20840 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
20850 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
20860 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
20870 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
20880 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
20890 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
208a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
208b0 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
208c0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
208d0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
208e0 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
208f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
20900 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
20910 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
20920 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20930 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
20940 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
20950 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
20960 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
20970 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20980 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
20990 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
209a0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
209b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
209c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
209d0 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
209e0 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
209f0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
20a00 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20a10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20a20 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
20a30 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
20a40 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20a50 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
20a60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20a70 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
20a80 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
20a90 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20aa0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
20ab0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20ac0 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
20ad0 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
20ae0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20af0 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
20b00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20b10 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
20b20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
20b30 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
20b40 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
20b50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20b60 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
20b70 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
20b80 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
20b90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
20ba0 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20  ECURSIVE        
20bb0 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c      33   /* NULL
20bc0 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
20bd0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a              */..
20be0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20bf0 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
20c00 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
20c10 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
20c20 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e3.**.** These r
20c30 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
20c40 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
20c50 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
20c60 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
20c70 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
20c80 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
20c90 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
20ca0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
20cb0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
20cc0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
20cd0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
20ce0 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
20cf0 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
20d00 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
20d10 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
20d20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
20d30 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
20d40 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
20d50 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
20d60 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
20d70 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
20d80 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
20d90 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
20da0 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
20db0 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
20dc0 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
20dd0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
20de0 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
20df0 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
20e00 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
20e10 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
20e20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
20e30 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
20e40 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
20e50 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
20e60 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
20e70 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
20e80 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
20e90 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
20ea0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
20eb0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
20ec0 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
20ed0 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
20ee0 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
20ef0 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
20f00 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
20f10 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
20f20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
20f30 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
20f40 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
20f50 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
20f60 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
20f70 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
20f80 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
20f90 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
20fa0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
20fb0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
20fc0 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
20fd0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
20fe0 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
20ff0 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
21000 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
21010 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
21020 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
21030 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
21040 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
21050 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
21060 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
21070 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
21080 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
21090 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
210a0 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
210b0 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
210c0 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
210d0 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
210e0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
210f0 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
21100 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
21110 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
21120 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
21130 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
21140 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
21150 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
21160 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
21170 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
21180 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
21190 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
211a0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
211b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
211c0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
211d0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73   sqlite3_trace(s
211e0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
211f0 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
21200 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
21210 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
21220 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
21230 4c 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  L void *SQLITE_S
21240 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70  TDCALL sqlite3_p
21250 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
21260 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
21270 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
21280 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
21290 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
212a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
212b0 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
212c0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48  allbacks.** METH
212d0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
212e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
212f0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
21300 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
21310 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
21320 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
21330 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
21340 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
21350 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
21360 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
21370 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
21380 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
21390 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
213a0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
213b0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
213c0 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
213d0 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
213e0 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
213f0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
21400 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
21410 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
21420 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
21430 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
21440 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
21450 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
21460 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
21470 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
21480 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
21490 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d   is the approxim
214a0 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  ate number of .*
214b0 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
214c0 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
214d0 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
214e0 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
214f0 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
21500 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
21510 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20  lback X.  ^If N 
21520 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65  is less than one
21530 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
21540 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73  ss.** handler is
21550 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
21560 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20   ^Only a single 
21570 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
21580 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20   may be defined 
21590 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a  at one time per.
215a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
215b0 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e  nection]; settin
215c0 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73  g a new progress
215d0 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73   handler cancels
215e0 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e   the.** old one.
215f0 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d    ^Setting param
21600 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64  eter X to NULL d
21610 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67  isables the prog
21620 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
21630 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68   ^The progress h
21640 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64  andler is also d
21650 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
21660 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20  ng N to a value 
21670 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a  less.** than 1..
21680 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  **.** ^If the pr
21690 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
216a0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
216b0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
216c0 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
216d0 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
216e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
216f0 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
21700 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
21710 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
21720 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
21730 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
21740 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
21750 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
21760 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
21770 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
21780 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21790 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
217a0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
217b0 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
217c0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
217d0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
217e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
217f0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
21800 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
21810 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
21820 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
21830 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
21840 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c  graph..**.*/.SQL
21850 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
21860 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
21870 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
21880 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
21890 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
218a0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
218b0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
218c0 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
218d0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
218e0 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71   CONSTRUCTOR: sq
218f0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
21900 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
21910 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
21920 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
21930 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
21940 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
21950 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
21960 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
21970 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
21980 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
21990 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
219a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
219b0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
219c0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
219d0 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
219e0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
219f0 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
21a00 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
21a10 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
21a20 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
21a30 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
21a40 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
21a50 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
21a60 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
21a70 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
21a80 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
21a90 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
21aa0 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
21ab0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
21ac0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
21ad0 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
21ae0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
21af0 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
21b00 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
21b10 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
21b20 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
21b30 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
21b40 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
21b50 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
21b60 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
21b70 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
21b80 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
21b90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
21ba0 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
21bb0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
21bc0 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
21bd0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
21be0 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
21bf0 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
21c00 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
21c10 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
21c20 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
21c30 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
21c40 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
21c50 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
21c60 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20  ncoding will be 
21c70 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61  UTF-8 for databa
21c80 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e  ses created usin
21c90 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  g.** sqlite3_ope
21ca0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
21cb0 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20  pen_v2().  ^The 
21cc0 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
21cd0 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a   for databases.*
21ce0 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  * created using 
21cf0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
21d00 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20   will be UTF-16 
21d10 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
21d20 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20  te order..**.** 
21d30 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
21d40 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
21d50 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
21d60 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
21d70 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
21d80 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
21d90 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
21da0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
21db0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
21dc0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
21dd0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
21de0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
21df0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
21e00 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
21e10 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
21e20 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
21e30 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
21e40 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
21e50 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
21e60 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
21e70 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
21e80 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
21e90 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
21ea0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
21eb0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
21ec0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
21ed0 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
21ee0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
21ef0 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
21f00 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
21f10 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
21f20 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
21f30 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
21f40 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
21f50 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
21f60 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
21f70 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
21f80 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c  N_PRIVATECACHE],
21f90 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
21fa0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a  OPEN_URI] flags:
21fb0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
21fc0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
21fd0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
21fe0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
21ff0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
22000 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
22010 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
22020 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
22030 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
22040 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
22050 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
22060 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
22070 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
22080 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22090 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
220a0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
220b0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
220c0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
220d0 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
220e0 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
220f0 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
22100 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
22110 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
22120 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
22130 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
22140 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
22150 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
22160 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
22170 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
22180 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
22190 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
221a0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
221b0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
221c0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
221d0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
221e0 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
221f0 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f  ated if.** it do
22200 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
22210 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
22220 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
22230 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
22240 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
22250 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
22260 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
22270 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
22280 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
22290 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
222a0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
222b0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
222c0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
222d0 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61  wn above optiona
222e0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
222f0 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49  h other.** [SQLI
22300 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
22310 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a   | SQLITE_OPEN_*
22320 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74   bits].** then t
22330 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
22340 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
22350 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
22360 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
22370 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
22380 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
22390 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
223a0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
223b0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
223c0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
223d0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
223e0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
223f0 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
22400 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
22410 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
22420 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
22430 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
22440 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
22450 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
22460 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
22470 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
22480 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
22490 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
224a0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
224b0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
224c0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
224d0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
224e0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
224f0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
22500 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
22510 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
22520 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
22530 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
22540 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
22550 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
22560 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
22570 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
22580 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
22590 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
225a0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
225b0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
225c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
225d0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
225e0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
225f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
22600 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
22610 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
22620 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
22630 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
22640 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
22650 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
22660 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22670 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
22680 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
22690 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
226a0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
226b0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
226c0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
226d0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
226e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
226f0 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
22700 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
22710 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
22720 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
22730 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
22740 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
22750 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
22760 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
22770 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
22780 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
22790 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
227a0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
227b0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
227c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
227d0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
227e0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
227f0 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
22800 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22810 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
22820 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
22830 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
22840 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
22850 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
22860 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
22870 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
22880 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
22890 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
228a0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
228b0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
228c0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
228d0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
228e0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
228f0 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
22900 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
22910 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
22920 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
22930 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
22940 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
22950 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
22960 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
22970 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
22980 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
22990 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
229a0 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
229b0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
229c0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
229d0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
229e0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
229f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22a00 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
22a10 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
22a20 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65  enames in sqlite
22a30 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55  3_open()]] <h3>U
22a40 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33  RI Filenames</h3
22a50 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49  >.**.** ^If [URI
22a60 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72   filename] inter
22a70 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
22a80 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69  bled, and the fi
22a90 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
22aa0 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22  ** begins with "
22ab0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65  file:", then the
22ac0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74   filename is int
22ad0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52  erpreted as a UR
22ae0 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e  I. ^URI.** filen
22af0 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
22b00 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  on is enabled if
22b10 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
22b20 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a  N_URI] flag is.*
22b30 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75  * set in the fou
22b40 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
22b50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22b60 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
22b70 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
22b80 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
22b90 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
22ba0 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
22bb0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
22bc0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
22bd0 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
22be0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
22bf0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
22c00 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c  on..** As of SQL
22c10 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
22c20 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  7, URI filename 
22c30 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
22c40 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
22c50 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
22c60 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
22c70 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
22c80 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
22c90 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
22ca0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
22cb0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
22cc0 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
22cd0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
22ce0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
22cf0 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
22d00 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
22d10 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
22d20 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
22d30 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
22d40 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
22d50 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
22d60 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
22d70 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
22d80 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
22d90 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
22da0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
22db0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
22dc0 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
22dd0 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
22de0 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
22df0 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
22e00 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
22e10 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
22e20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
22e30 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
22e40 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
22e50 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
22e60 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
22e70 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
22e80 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
22e90 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
22ea0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
22eb0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
22ec0 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
22ed0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
22ee0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
22ef0 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
22f00 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
22f10 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
22f20 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
22f30 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
22f40 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
22f50 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
22f60 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
22f70 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
22f80 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
22f90 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74   ^(On windows, t
22fa0 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65  he first compone
22fb0 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74  nt of an absolut
22fc0 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20  e path .** is a 
22fd0 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74  drive specificat
22fe0 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e  ion (e.g. "C:").
22ff0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20  )^.**.** [[core 
23000 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65  URI query parame
23010 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75  ters]].** The qu
23020 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
23030 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61   a URI may conta
23040 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  in parameters th
23050 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  at are interpret
23060 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20  ed.** either by 
23070 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f  SQLite itself, o
23080 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75  r by a [VFS | cu
23090 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
230a0 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
230b0 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c  ite and its buil
230c0 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74  t-in [VFSes] int
230d0 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f  erpret the.** fo
230e0 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61  llowing query pa
230f0 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
23100 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
23110 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
23120 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
23130 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
23140 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
23150 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
23160 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
23170 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
23180 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
23190 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
231a0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
231b0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
231c0 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
231d0 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
231e0 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
231f0 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
23200 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
23210 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
23220 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
23230 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
23240 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
23250 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
23260 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
23270 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
23280 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
23290 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
232a0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
232b0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
232c0 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
232d0 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
232e0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
232f0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
23300 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
23310 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
23320 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
23330 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
23340 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
23350 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
23360 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
23370 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
23380 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
23390 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
233a0 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
233b0 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
233c0 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
233d0 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
233e0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
233f0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
23400 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
23410 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
23420 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
23430 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
23440 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
23450 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
23460 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
23470 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
23480 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
23490 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
234a0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
234b0 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
234c0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
234d0 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
234e0 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
234f0 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
23500 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
23510 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
23520 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
23530 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
23540 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
23550 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
23560 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
23570 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
23580 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
23590 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
235a0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20  E_OPEN_CREATE.  
235b0 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
235c0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65  ion is.**     se
235d0 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68  t to "memory" th
235e0 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65  en a pure [in-me
235f0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74  mory database] t
23600 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a  hat never reads.
23610 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73  **     or writes
23620 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73   from disk is us
23630 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72  ed. ^It is an er
23640 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
23650 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20   value for.**   
23660 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d    the mode param
23670 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73  eter that is les
23680 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
23690 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
236a0 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20  d by.**     the 
236b0 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20  flags passed in 
236c0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
236d0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
236e0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
236f0 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
23700 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
23710 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
23720 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
23730 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
23740 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
23750 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
23760 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
23770 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
23780 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
23790 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
237a0 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
237b0 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
237c0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
237d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
237e0 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
237f0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
23800 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
23810 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
23820 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
23830 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
23840 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
23850 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
23860 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
23870 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
23880 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
23890 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
238a0 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
238b0 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
238c0 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72  des any behavior
238d0 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65   requested by se
238e0 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c  tting.**     SQL
238f0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
23900 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f  CACHE or SQLITE_
23910 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
23920 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c   flag..**.**  <l
23930 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20  i> <b>psow</b>: 
23940 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65  ^The psow parame
23950 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68  ter indicates wh
23960 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
23970 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61  .**     [powersa
23980 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72  fe overwrite] pr
23990 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64  operty does or d
239a0 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f  oes not apply to
239b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72   the.**     stor
239c0 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69  age media on whi
239d0 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ch the database 
239e0 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a  file resides..**
239f0 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c  .**  <li> <b>nol
23a00 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f  ock</b>: ^The no
23a10 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  lock parameter i
23a20 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
23a30 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  y parameter.**  
23a40 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20     which if set 
23a50 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f  disables file lo
23a60 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63  cking in rollbac
23a70 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e  k journal modes.
23a80 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73    This.**     is
23a90 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65   useful for acce
23aa0 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65  ssing a database
23ab0 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d   on a filesystem
23ac0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a   that does not.*
23ad0 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f  *     support lo
23ae0 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a  cking.  Caution:
23af0 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75    Database corru
23b00 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75  ption might resu
23b10 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20  lt if two.**    
23b20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73   or more process
23b30 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20  es write to the 
23b40 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e  same database an
23b50 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f  d any one of tho
23b60 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73  se.**     proces
23b70 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d  ses uses nolock=
23b80 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  1..**.**  <li> <
23b90 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a  b>immutable</b>:
23ba0 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20   ^The immutable 
23bb0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
23bc0 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20  oolean query.** 
23bd0 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68      parameter th
23be0 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  at indicates tha
23bf0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  t the database f
23c00 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e  ile is stored on
23c10 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c  .**     read-onl
23c20 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20  y media.  ^When 
23c30 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74  immutable is set
23c40 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  , SQLite assumes
23c50 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
23c60 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63   database file c
23c70 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
23c80 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63  , even by a proc
23c90 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a  ess with higher.
23ca0 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65  **     privilege
23cb0 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74  , and so the dat
23cc0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
23cd0 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c  read-only and al
23ce0 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20  l locking.**    
23cf0 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65   and change dete
23d00 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65  ction is disable
23d10 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74  d.  Caution: Set
23d20 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62  ting the immutab
23d30 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72  le.**     proper
23d40 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ty on a database
23d50 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20   file that does 
23d60 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63  in fact change c
23d70 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20  an result.**    
23d80 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75   in incorrect qu
23d90 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f  ery results and/
23da0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  or [SQLITE_CORRU
23db0 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20  PT] errors..**  
23dc0 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51     See also: [SQ
23dd0 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
23de0 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20  ABLE]..**       
23df0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
23e00 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
23e10 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72  nknown parameter
23e20 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f   in the query co
23e30 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
23e40 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72   is not an.** er
23e50 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72  ror.  Future ver
23e60 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
23e70 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64  might understand
23e80 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72   additional quer
23e90 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  y.** parameters.
23ea0 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61    See "[query pa
23eb0 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70  rameters with sp
23ec0 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f  ecial meaning to
23ed0 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a   SQLite]" for.**
23ee0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
23ef0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  rmation..**.** [
23f00 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  [URI filename ex
23f10 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49  amples]] <h3>URI
23f20 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
23f30 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74  es</h3>.**.** <t
23f40 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20  able border="1" 
23f50 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c  align=center cel
23f60 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c  lpadding=5>.** <
23f70 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65  tr><th> URI file
23f80 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c  names <th> Resul
23f90 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  ts.** <tr><td> f
23fa0 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e  ile:data.db <td>
23fb0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
23fc0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
23fd0 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
23fe0 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a  rent directory..
23ff0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
24000 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
24010 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20  .db<br>.**      
24020 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65      file:///home
24030 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
24040 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r> .**          
24050 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74  file://localhost
24060 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
24070 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a  db <br> <td> .**
24080 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
24090 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
240a0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
240b0 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  a.db"..** <tr><t
240c0 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74  d> file://darkst
240d0 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ar/home/fred/dat
240e0 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
240f0 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
24100 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e   "darkstar" is n
24110 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20  ot a recognized 
24120 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74  authority..** <t
24130 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69  r><td style="whi
24140 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22  te-space:nowrap"
24150 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
24160 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65  ile:///C:/Docume
24170 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74  nts%20and%20Sett
24180 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f  ings/fred/Deskto
24190 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20  p/data.db.**    
241a0 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e   <td> Windows on
241b0 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c  ly: Open the fil
241c0 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66  e "data.db" on f
241d0 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e  red's desktop on
241e0 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20   drive.**       
241f0 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74     C:. Note that
24200 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e   the %20 escapin
24210 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c  g in this exampl
24220 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c  e is not strictl
24230 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  y .**          n
24240 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65  ecessary - space
24250 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20   characters can 
24260 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c  be used literall
24270 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  y.**          in
24280 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a   URI filenames..
24290 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
242a0 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f  :data.db?mode=ro
242b0 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c  &cache=private <
242c0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
242d0 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61   Open file "data
242e0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
242f0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f  ent directory fo
24300 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65  r read-only acce
24310 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss..**          
24320 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
24330 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
24340 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69  red-cache mode i
24350 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20  s enabled by.** 
24360 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74           default
24370 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20  , use a private 
24380 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cache..** <tr><t
24390 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
243a0 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75  ed/data.db?vfs=u
243b0 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e  nix-dotfile <td>
243c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
243d0 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  n file "/home/fr
243e0 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65  ed/data.db". Use
243f0 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
24400 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a   "unix-dotfile".
24410 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
24420 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20   uses dot-files 
24430 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69  in place of posi
24440 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69  x advisory locki
24450 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ng..** <tr><td> 
24460 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
24470 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20  e=readonly <td> 
24480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
24490 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79  error. "readonly
244a0 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64  " is not a valid
244b0 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20   option for the 
244c0 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72  "mode" parameter
244d0 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ..** </table>.**
244e0 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63  .** ^URI hexadec
244f0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
24500 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20  ences (%HH) are 
24510 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
24520 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a   the path and.**
24530 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
24540 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65  s of a URI. A he
24550 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
24560 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73   sequence consis
24570 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65  ts of a.** perce
24580 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20  nt sign - "%" - 
24590 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63  followed by exac
245a0 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69  tly two hexadeci
245b0 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73  mal digits .** s
245c0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74  pecifying an oct
245d0 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72  et value. ^Befor
245e0 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75  e the path or qu
245f0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
24600 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  f a.** URI filen
24610 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65  ame are interpre
24620 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e  ted, they are en
24630 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
24640 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65  8 and all .** he
24650 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
24660 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61   sequences repla
24670 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ced by a single 
24680 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  byte containing 
24690 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
246a0 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74  ding octet. If t
246b0 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65  his process gene
246c0 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64  rates an invalid
246d0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c   UTF-8 encoding,
246e0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20  .** the results 
246f0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
24700 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
24710 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
24720 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
24730 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
24740 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
24750 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
24760 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
24770 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
24780 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
24790 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
247a0 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
247b0 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
247c0 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
247d0 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
247e0 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
247f0 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
24800 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
24810 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
24820 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
24830 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
24840 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c  en_v2()..**.** <
24850 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
24860 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a  s Runtime users:
24870 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72  </b>  The tempor
24880 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75  ary directory mu
24890 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69  st be set.** pri
248a0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71  or to calling sq
248b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
248c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
248d0 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76  ).  Otherwise, v
248e0 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72  arious.** featur
248f0 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20  es that require 
24900 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f  the use of tempo
24910 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66  rary files may f
24920 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ail..**.** See a
24930 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65  lso: [sqlite3_te
24940 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f  mp_directory].*/
24950 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
24960 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
24970 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
24980 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
24990 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
249a0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
249b0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
249c0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
249d0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
249e0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
249f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
24a00 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
24a10 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
24a20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
24a30 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
24a40 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
24a50 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
24a60 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
24a70 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
24a80 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
24a90 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
24aa0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
24ab0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24ac0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
24ad0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
24ae0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
24af0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
24b00 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
24b10 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
24b20 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
24b30 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
24b40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
24b50 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
24b60 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
24b70 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
24b80 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
24b90 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
24ba0 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
24bb0 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
24bc0 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
24bd0 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
24be0 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
24bf0 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
24c00 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
24c10 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
24c20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
24c30 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
24c40 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
24c50 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
24c60 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
24c70 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
24c80 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
24c90 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
24ca0 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
24cb0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
24cc0 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
24cd0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
24ce0 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
24cf0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
24d00 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
24d10 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
24d20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
24d30 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
24d40 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
24d50 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
24d60 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
24d70 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
24d80 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
24d90 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
24da0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
24db0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
24dc0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
24dd0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
24de0 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
24df0 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
24e00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
24e10 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
24e20 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
24e30 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
24e40 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
24e50 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
24e60 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
24e70 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
24e80 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
24e90 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
24ea0 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
24eb0 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
24ec0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
24ed0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
24ee0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
24ef0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
24f00 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
24f10 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
24f20 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
24f30 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
24f40 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
24f50 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
24f60 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
24f70 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
24f80 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
24f90 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
24fa0 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
24fb0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
24fc0 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
24fd0 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
24fe0 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
24ff0 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
25000 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
25010 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
25020 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
25030 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
25040 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
25050 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
25060 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
25070 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
25080 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
25090 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
250a0 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
250b0 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
250c0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
250d0 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
250e0 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
250f0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
25100 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
25110 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
25120 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
25130 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
25140 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
25150 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
25160 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
25170 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25180 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
25190 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
251a0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
251b0 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
251c0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
251d0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
251e0 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
251f0 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
25200 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
25210 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
25220 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
25230 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
25240 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
25250 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
25260 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
25270 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
25280 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
25290 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
252a0 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
252b0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
252c0 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
252d0 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
252e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
252f0 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
25300 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
25310 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
25320 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
25330 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
25340 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
25350 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
25360 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
25370 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
25380 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
25390 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c  esirable..*/.SQL
253a0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
253b0 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
253c0 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  LL sqlite3_uri_p
253d0 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63  arameter(const c
253e0 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20  har *zFilename, 
253f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
25400 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  am);.SQLITE_API 
25410 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
25420 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  LL sqlite3_uri_b
25430 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
25440 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
25450 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
25460 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c  t bDefault);.SQL
25470 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
25480 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44  int64 SQLITE_STD
25490 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69  CALL sqlite3_uri
254a0 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61  _int64(const cha
254b0 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  r*, const char*,
254c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
254d0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
254e0 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
254f0 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d  nd Messages.** M
25500 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
25510 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
25520 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33  t recent sqlite3
25530 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f  _* API call asso
25540 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20  ciated with .** 
25550 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25560 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20  tion] D failed, 
25570 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
25580 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65  _errcode(D) inte
25590 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
255a0 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
255b0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65  sult code] or [e
255c0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
255d0 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a  ode] for that.**
255e0 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66   API call..** If
255f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
25600 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75   API call was su
25610 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65  ccessful,.** the
25620 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
25630 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
25640 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
25650 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  efined..** ^The 
25660 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
25670 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
25680 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
25690 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
256a0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
256b0 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
256c0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
256d0 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
256e0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
256f0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
25700 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
25710 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
25720 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
25730 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
25740 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
25750 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
25760 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
25770 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
25780 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
25790 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
257a0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
257b0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
257c0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
257d0 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
257e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
257f0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
25800 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
25810 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
25820 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
25830 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
25840 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
25850 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
25860 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
25870 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
25880 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
25890 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
258a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
258b0 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66  _errstr() interf
258c0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
258d0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
258e0 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65   text.** that de
258f0 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73  scribes the [res
25900 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54  ult code], as UT
25910 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  F-8..** ^(Memory
25920 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
25930 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
25940 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
25950 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d  ernally.** and m
25960 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64  ust not be freed
25970 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
25980 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ion)^..**.** Whe
25990 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
259a0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
259b0 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
259c0 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
259d0 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
259e0 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
259f0 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
25a00 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
25a10 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
25a20 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
25a30 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
25a40 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
25a50 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
25a60 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
25a70 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
25a80 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
25a90 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
25aa0 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
25ab0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
25ac0 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
25ad0 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
25ae0 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
25af0 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
25b00 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
25b10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
25b20 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
25b30 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
25b40 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
25b50 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
25b60 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
25b70 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
25b80 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
25b90 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
25ba0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
25bb0 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
25bc0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
25bd0 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
25be0 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
25bf0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
25c00 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
25c10 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
25c20 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
25c30 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
25c40 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
25c50 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
25c60 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
25c70 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
25c80 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
25c90 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
25ca0 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
25cb0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
25cc0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
25cd0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
25ce0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51  sqlite3 *db);.SQ
25cf0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
25d00 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
25d10 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
25d20 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
25d30 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
25d40 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
25d50 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
25d60 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
25d70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
25d80 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  nst void *SQLITE
25d90 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
25da0 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
25db0 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
25dc0 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
25dd0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
25de0 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
25df0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25e00 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
25e10 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
25e20 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
25e30 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
25e40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25e50 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
25e60 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
25e70 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
25e80 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
25e90 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61  ement that.** ha
25ea0 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20  s been compiled 
25eb0 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d  into binary form
25ec0 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f   and is ready to
25ed0 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a   be evaluated..*
25ee0 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61  *.** Think of ea
25ef0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
25f00 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63   as a separate c
25f10 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e  omputer program.
25f20 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61    The.** origina
25f30 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f  l SQL text is so
25f40 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72  urce code.  A pr
25f50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25f60 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74   object .** is t
25f70 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65  he compiled obje
25f80 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51  ct code.  All SQ
25f90 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  L must be conver
25fa0 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72  ted into a.** pr
25fb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25fc0 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62   before it can b
25fd0 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  e run..**.** The
25fe0 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61   life-cycle of a
25ff0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
26000 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c  ent object usual
26010 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69  ly goes like thi
26020 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
26030 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
26040 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
26050 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  ent object using
26060 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26070 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e  e_v2()]..** <li>
26080 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
26090 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69  [parameters] usi
260a0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
260b0 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
260c0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
260d0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
260e0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
260f0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
26100 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
26110 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
26120 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
26130 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
26140 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
26150 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
26160 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
26170 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
26180 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
26190 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
261a0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
261b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
261c0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65  ** </ol>.*/.type
261d0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
261e0 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
261f0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
26200 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
26210 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44  Limits.** METHOD
26220 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
26230 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
26240 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
26250 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
26260 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
26270 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
26280 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
26290 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
262a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
262b0 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
262c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
262d0 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
262e0 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
262f0 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
26300 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
26310 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
26320 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
26330 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
26340 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
26350 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
26360 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
26370 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
26380 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
26390 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
263a0 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
263b0 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
263c0 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
263d0 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
263e0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
263f0 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
26400 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
26410 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
26420 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
26430 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
26440 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
26450 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
26460 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
26470 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
26480 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
26490 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
264a0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
264b0 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
264c0 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
264d0 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
264e0 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
264f0 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
26500 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
26510 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
26520 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
26530 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
26540 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
26550 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
26560 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
26570 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
26580 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
26590 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
265a0 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
265b0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
265c0 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
265d0 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
265e0 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
265f0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
26600 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
26610 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
26620 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
26630 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
26640 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
26650 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
26660 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
26670 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
26680 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
26690 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
266a0 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
266b0 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
266c0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
266d0 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
266e0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
266f0 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
26700 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
26710 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
26720 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
26730 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
26740 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
26750 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
26760 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
26770 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
26780 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
26790 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
267a0 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
267b0 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
267c0 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
267d0 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
267e0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
267f0 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
26800 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
26810 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
26820 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
26830 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
26840 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
26850 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
26860 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
26870 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
26880 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
26890 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
268a0 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
268b0 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
268c0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
268d0 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
268e0 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
268f0 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
26900 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
26910 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
26920 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
26930 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
26940 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
26950 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
26960 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
26970 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
26980 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
26990 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
269a0 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
269b0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
269c0 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  es..*/.SQLITE_AP
269d0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
269e0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 6d  CALL sqlite3_lim
269f0 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
26a00 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
26a10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26a20 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
26a30 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
26a40 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
26a50 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
26a60 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
26a70 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
26a80 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
26a90 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
26aa0 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
26ab0 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
26ac0 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
26ad0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
26ae0 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
26af0 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
26b00 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
26b10 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
26b20 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
26b30 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
26b40 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
26b50 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
26b60 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
26b70 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
26b80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
26b90 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
26ba0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
26bb0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26bc0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
26bd0 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
26be0 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
26bf0 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
26c00 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26c10 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
26c20 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
26c30 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
26c40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26c50 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
26c60 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
26c70 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
26c80 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26c90 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
26ca0 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  N]] ^(<dt>SQLITE
26cb0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
26cc0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26cd0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
26ce0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
26cf0 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
26d00 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
26d10 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
26d20 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
26d30 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
26d40 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
26d50 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
26d60 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
26d70 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
26d80 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26d90 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
26da0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
26db0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
26dc0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26dd0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
26de0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
26df0 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
26e00 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
26e10 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26e20 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d  COMPOUND_SELECT]
26e30 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26e40 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
26e50 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
26e60 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
26e70 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
26e80 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
26e90 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
26ea0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
26eb0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
26ec0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
26ed0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
26ee0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26ef0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
26f00 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
26f10 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
26f20 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
26f30 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
26f40 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
26f50 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20    This limit is 
26f60 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  not currently.**
26f70 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67   enforced, thoug
26f80 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  h that might be 
26f90 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75  added in some fu
26fa0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
26fb0 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29  ** SQLite.</dd>)
26fc0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26fd0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
26fe0 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ARG]] ^(<dt>SQLI
26ff0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
27000 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
27010 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
27020 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
27030 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
27040 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
27050 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
27060 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51  ACHED]] ^(<dt>SQ
27070 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
27080 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
27090 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
270a0 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
270b0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
270c0 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
270d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
270e0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
270f0 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  NGTH]].** ^(<dt>
27100 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
27110 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
27120 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27130 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
27140 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
27150 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
27160 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
27170 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
27180 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
27190 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
271a0 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e  LE_NUMBER]].** ^
271b0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
271c0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
271d0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
271e0 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
271f0 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
27200 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
27210 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
27220 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27230 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
27240 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
27250 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
27260 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
27270 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
27280 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
27290 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
272a0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
272b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
272c0 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c  ER_THREADS]] ^(<
272d0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
272e0 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f  WORKER_THREADS</
272f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
27300 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
27310 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65   auxiliary worke
27320 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20 61  r threads that a
27330 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70   single.** [prep
27340 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27350 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29  may start.</dd>)
27360 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ^.** </dl>.*/.#d
27370 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27380 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
27390 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
273a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
273b0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
273c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
273d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
273e0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
273f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
27400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27410 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
27420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27430 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
27440 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
27450 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
27460 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
27470 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
27480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27490 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
274a0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
274b0 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
274c0 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
274d0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
274e0 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
274f0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
27500 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
27510 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
27520 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
27530 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
27540 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
27550 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
27560 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
27570 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
27580 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
27590 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f   SQLITE_LIMIT_WO
275a0 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20 20  RKER_THREADS    
275b0 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a         11../*.**
275c0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
275d0 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
275e0 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  ement.** KEYWORD
275f0 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e  S: {SQL statemen
27600 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d  t compiler}.** M
27610 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
27620 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73  * CONSTRUCTOR: s
27630 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
27640 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
27650 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75  SQL query, it mu
27660 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
27670 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
27680 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
27690 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
276a0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
276b0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
276c0 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73  gument, "db", is
276d0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
276e0 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65  nection] obtaine
276f0 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f  d from a.** prio
27700 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
27710 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
27720 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
27730 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  open_v2()] or.**
27740 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
27750 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61  ()].  The databa
27760 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
27770 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e  st not have been
27780 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
27790 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
277a0 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
277b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
277c0 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
277d0 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
277e0 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
277f0 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
27800 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
27810 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27820 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
27830 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
27840 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
27850 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
27860 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
27870 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
27880 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74  .** ^If the nByt
27890 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65  e argument is ne
278a0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71  gative, then zSq
278b0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
278c0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
278d0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
278e0 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74  f nByte is posit
278f0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
27900 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
27910 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
27920 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74   zSql.  ^If nByt
27930 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  e is zero, then 
27940 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  no prepared.** s
27950 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65  tatement is gene
27960 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  rated..** If the
27970 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68   caller knows th
27980 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
27990 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
279a0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a  rminated, then.*
279b0 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  * there is a sma
279c0 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ll performance a
279d0 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73  dvantage to pass
279e0 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
279f0 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
27a00 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
27a10 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
27a20 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
27a30 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
27a40 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
27a50 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
27a60 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
27a70 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
27a80 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
27a90 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
27aa0 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
27ab0 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
27ac0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
27ad0 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
27ae0 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
27af0 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
27b00 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
27b10 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
27b20 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
27b30 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
27b40 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
27b50 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
27b60 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
27b70 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
27b80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
27b90 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
27ba0 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
27bb0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
27bc0 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
27bd0 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
27be0 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
27bf0 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
27c00 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
27c10 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
27c20 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
27c30 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
27c40 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
27c50 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
27c60 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
27c70 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
27c80 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
27c90 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
27ca0 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
27cb0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
27cc0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
27cd0 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
27ce0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
27cf0 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
27d00 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
27d10 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
27d20 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
27d30 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
27d40 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
27d50 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
27d60 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
27d70 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
27d80 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
27d90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
27da0 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
27db0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
27dc0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
27dd0 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
27de0 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
27df0 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
27e00 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
27e10 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
27e20 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
27e30 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
27e40 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
27e50 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
27e60 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
27e70 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
27e80 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
27e90 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
27ea0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
27eb0 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
27ec0 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
27ed0 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
27ee0 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
27ef0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
27f00 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
27f10 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
27f20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
27f30 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
27f40 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
27f50 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
27f60 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
27f70 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
27f80 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
27f90 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
27fa0 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
27fb0 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
27fc0 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
27fd0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
27fe0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
27ff0 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
28000 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41   run it again. A
28010 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54  s many as [SQLIT
28020 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54  E_MAX_SCHEMA_RET
28030 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77  RY].** retries w
28040 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65  ill occur before
28050 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
28060 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74  gives up and ret
28070 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  urns an error..*
28080 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
28090 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
280a0 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
280b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
280c0 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
280d0 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
280e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
280f0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
28100 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
28110 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
28120 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
28130 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
28140 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
28150 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
28160 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
28170 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
28180 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
28190 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
281a0 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
281b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
281c0 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
281d0 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
281e0 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
281f0 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
28200 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
28210 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
28220 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
28230 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
28240 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
28250 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
28260 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
28270 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
28280 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
28290 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
282a0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
282b0 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
282c0 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
282d0 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
282e0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
282f0 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
28300 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
28310 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
28320 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
28330 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
28340 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
28350 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
28360 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
28370 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
28380 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
28390 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
283a0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
283b0 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
283c0 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
283d0 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
283e0 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
283f0 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
28400 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
28410 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
28420 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
28430 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
28440 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
28450 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
28460 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
28470 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
28480 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
28490 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
284a0 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
284b0 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
284c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
284d0 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
284e0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
284f0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f  s enabled..** </
28500 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
28510 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
28520 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
28530 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
28540 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
28550 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
28560 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
28570 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
28580 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
28590 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
285a0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
285b0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
285c0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
285d0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
285e0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
285f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
28600 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
28610 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
28620 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
28630 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
28640 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
28650 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
28660 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c  f zSql */.);.SQL
28670 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
28680 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
28690 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
286a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
286b0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
286c0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
286d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
286e0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
286f0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
28700 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
28710 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
28720 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
28730 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
28740 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
28750 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
28760 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
28770 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
28780 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
28790 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
287a0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
287b0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
287c0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c  f zSql */.);.SQL
287d0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
287e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
287f0 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
28800 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
28810 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
28820 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
28830 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
28840 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
28850 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
28860 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
28870 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
28880 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
28890 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
288a0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
288b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
288c0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
288d0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
288e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
288f0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
28900 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
28910 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
28920 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c  f zSql */.);.SQL
28930 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
28940 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
28950 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
28960 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
28970 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
28980 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
28990 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
289a0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
289b0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
289c0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
289d0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
289e0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
289f0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
28a00 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
28a10 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
28a20 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
28a30 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
28a40 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
28a50 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
28a60 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
28a70 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
28a80 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
28a90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28aa0 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
28ab0 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54  ement SQL.** MET
28ac0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
28ad0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
28ae0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
28af0 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
28b00 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
28b10 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
28b20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
28b30 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
28b40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
28b50 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
28b60 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
28b70 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
28b80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28b90 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
28ba0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
28bb0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
28bc0 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
28bd0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
28be0 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
28bf0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
28c00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
28c10 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
28c20 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
28c30 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
28c40 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
28c50 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
28c60 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
28c70 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
28c80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
28c90 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
28ca0 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
28cb0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
28cc0 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
28cd0 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
28ce0 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
28cf0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
28d00 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
28d10 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
28d20 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28d30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
28d40 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
28d50 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
28d60 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
28d70 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
28d80 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
28d90 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
28da0 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
28db0 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
28dc0 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
28dd0 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
28de0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
28df0 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
28e00 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
28e10 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
28e20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
28e30 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
28e40 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
28e50 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
28e60 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
28e70 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
28e80 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
28e90 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
28ea0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
28eb0 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
28ec0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
28ed0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
28ee0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
28ef0 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
28f00 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
28f10 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
28f20 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
28f30 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
28f40 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
28f50 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
28f60 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
28f70 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
28f80 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
28f90 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
28fa0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
28fb0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
28fc0 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
28fd0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
28fe0 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
28ff0 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
29000 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
29010 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
29020 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
29030 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
29040 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
29050 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
29060 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
29070 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
29080 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
29090 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
290a0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
290b0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
290c0 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
290d0 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
290e0 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
290f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
29100 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
29110 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
29120 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
29130 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
29140 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
29150 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
29160 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  k..*/.SQLITE_API
29170 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
29180 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ALL sqlite3_stmt
29190 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
291a0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
291b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
291c0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
291d0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
291e0 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
291f0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
29200 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
29210 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
29220 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66  t_busy(S) interf
29230 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
29240 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74   (non-zero) if t
29250 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
29260 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73  statement] S has
29270 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74   been stepped at
29280 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e   least once usin
29290 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  g .** [sqlite3_s
292a0 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20  tep(S)] but has 
292b0 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63  neither run to c
292c0 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72  ompletion (retur
292d0 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  ned.** [SQLITE_D
292e0 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ONE] from [sqlit
292f0 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72  e3_step(S)]) nor
29300 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75  .** been reset u
29310 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
29320 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73  set(S)].  ^The s
29330 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
29340 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  (S).** interface
29350 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69   returns false i
29360 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f S is a NULL po
29370 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20  inter.  If S is 
29380 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70  not a .** NULL p
29390 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f  ointer and is no
293a0 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
293b0 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64   valid [prepared
293c0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
293d0 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  bject, then the 
293e0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
293f0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
29400 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
29410 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
29420 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
29430 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20   in combination 
29440 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
29450 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61  mt()].** to loca
29460 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20  te all prepared 
29470 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
29480 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74  iated with a dat
29490 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63  abase .** connec
294a0 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e  tion that are in
294b0 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72   need of being r
294c0 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20  eset.  This can 
294d0 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20  be used,.** for 
294e0 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67  example, in diag
294f0 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20  nostic routines 
29500 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72  to search for pr
29510 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65  epared .** state
29520 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68  ments that are h
29530 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63  olding a transac
29540 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51  tion open..*/.SQ
29550 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
29560 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
29570 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71  te3_stmt_busy(sq
29580 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
29590 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
295a0 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
295b0 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
295c0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
295d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
295e0 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
295f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
29600 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
29610 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
29620 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
29630 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
29640 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
29650 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
29660 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
29670 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
29680 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
29690 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
296a0 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
296b0 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
296c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
296d0 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
296e0 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
296f0 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
29700 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
29710 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
29720 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
29730 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
29740 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
29750 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
29760 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
29770 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
29780 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29790 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
297a0 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
297b0 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
297c0 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
297d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
297e0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
297f0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
29800 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
29810 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
29820 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
29830 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
29840 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
29850 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29860 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ue.  The.** [sql
29870 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29  ite3_value_dup()
29880 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ] interface can 
29890 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74  be used to const
298a0 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70  ruct a new .** p
298b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
298c0 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75  _value from an u
298d0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
298e0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
298f0 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
29900 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
29910 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
29920 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
29930 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
29940 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c  ld.  An internal
29950 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
29960 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
29970 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
29980 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
29990 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
299a0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
299b0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
299c0 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
299d0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
299e0 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
299f0 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
29a00 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
29a10 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
29a20 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
29a30 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
29a40 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
29a50 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
29a60 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
29a70 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
29a80 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
29a90 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
29aa0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
29ab0 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
29ac0 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
29ad0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
29ae0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
29af0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
29b00 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
29b10 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
29b20 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
29b30 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
29b40 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
29b50 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
29b60 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
29b70 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
29b80 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
29b90 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
29ba0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
29bb0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
29bc0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
29bd0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
29be0 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
29bf0 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
29c00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29c10 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
29c20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
29c30 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
29c40 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
29c50 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
29c60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29c70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
29c80 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
29c90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
29ca0 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
29cb0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
29cc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
29cd0 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
29ce0 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
29cf0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29d00 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
29d10 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
29d20 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
29d30 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
29d40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
29d50 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  ue()]..** The [s
29d60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
29d70 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  b | sqlite3_valu
29d80 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79  e_type()] family
29d90 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
29da0 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63  s require protec
29db0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29dc0 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79  e objects..*/.ty
29dd0 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
29de0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
29df0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29e00 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
29e10 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ntext Object.**.
29e20 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
29e30 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
29e40 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
29e50 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
29e60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
29e70 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20  ext object.  ^A 
29e80 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
29e90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
29ea0 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
29eb0 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
29ec0 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
29ed0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
29ee0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
29ef0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29f00 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
29f10 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
29f20 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
29f30 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
29f40 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
29f50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
29f60 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
29f70 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
29f80 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
29f90 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
29fa0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
29fb0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
29fc0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
29fd0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
29fe0 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
29ff0 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
2a000 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
2a010 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2a020 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
2a030 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
2a040 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
2a050 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
2a060 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
2a070 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45  Statements.** KE
2a080 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
2a090 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
2a0a0 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
2a0b0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
2a0c0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
2a0d0 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
2a0e0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
2a0f0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
2a100 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  g}.** METHOD: sq
2a110 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2a120 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
2a130 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
2a140 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
2a150 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2a160 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
2a170 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
2a180 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
2a190 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
2a1a0 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
2a1b0 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
2a1c0 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
2a1d0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
2a1e0 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
2a1f0 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
2a200 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
2a210 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
2a220 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
2a230 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
2a240 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
2a250 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
2a260 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
2a270 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
2a280 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
2a290 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
2a2a0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
2a2b0 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
2a2c0 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
2a2d0 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
2a2e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
2a2f0 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
2a300 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2a310 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2a320 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
2a330 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2a340 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2a350 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2a360 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
2a370 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
2a380 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
2a390 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
2a3a0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
2a3b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a3c0 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
2a3d0 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
2a3e0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
2a3f0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
2a400 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
2a410 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
2a420 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
2a430 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
2a440 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
2a450 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
2a460 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
2a470 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
2a480 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
2a490 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
2a4a0 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
2a4b0 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
2a4c0 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
2a4d0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
2a4e0 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
2a4f0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
2a500 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
2a510 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
2a520 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
2a530 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2a540 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
2a550 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
2a560 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
2a570 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
2a580 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
2a590 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
2a5a0 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
2a5b0 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
2a5c0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
2a5d0 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
2a5e0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
2a5f0 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
2a600 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
2a610 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
2a620 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2a630 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
2a640 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
2a650 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
2a660 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
2a670 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a680 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2a690 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f  nd_text16().** o
2a6a0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  r sqlite3_bind_b
2a6b0 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  lob() is a NULL 
2a6c0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
2a6d0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2a6e0 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20  r.** is ignored 
2a6f0 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75  and the end resu
2a700 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  lt is the same a
2a710 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  s sqlite3_bind_n
2a720 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ull()..**.** ^(I
2a730 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
2a740 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
2a750 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
2a760 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
2a770 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
2a780 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
2a790 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
2a7a0 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
2a7b0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2a7c0 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
2a7d0 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
2a7e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
2a7f0 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
2a800 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2a810 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2a820 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2a830 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a840 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67  xt16().** is neg
2a850 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
2a860 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
2a870 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
2a880 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
2a890 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
2a8a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
2a8b0 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
2a8c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2a8d0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2a8e0 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  ) is negative, t
2a8f0 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76  hen.** the behav
2a900 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2a910 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
2a920 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
2a930 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
2a940 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
2a950 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
2a960 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a970 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65  xt16() or sqlite
2a980 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2a990 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72  then.** that par
2a9a0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
2a9b0 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
2a9c0 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
2a9d0 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
2a9e0 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
2a9f0 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
2aa00 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
2aa10 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
2aa20 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
2aa30 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
2aa40 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
2aa50 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
2aa60 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2aa70 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
2aa80 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
2aa90 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
2aaa0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
2aab0 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
2aac0 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
2aad0 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
2aae0 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
2aaf0 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
2ab00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
2ab10 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2ab20 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67   BLOB and string
2ab30 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61   binding interfa
2ab40 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74  ces.** is a dest
2ab50 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
2ab60 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2ab70 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
2ab80 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
2ab90 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
2aba0 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
2abb0 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
2abc0 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
2abd0 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
2abe0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
2abf0 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66  ll to bind API f
2ac00 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ails..** ^If the
2ac10 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2ac20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
2ac30 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
2ac40 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
2ac50 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
2ac60 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
2ac70 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
2ac80 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
2ac90 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
2aca0 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
2acb0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2acc0 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
2acd0 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
2ace0 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
2acf0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
2ad00 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
2ad10 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
2ad20 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
2ad30 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
2ad40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2ad50 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
2ad60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
2ad70 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2ad80 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2ad90 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  4() must be one 
2ada0 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  of.** [SQLITE_UT
2adb0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
2adc0 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  16], [SQLITE_UTF
2add0 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
2ade0 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f  E_UTF16LE].** to
2adf0 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63   specify the enc
2ae00 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78  oding of the tex
2ae10 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  t in the third p
2ae20 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a  arameter.  If.**
2ae30 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d   the sixth argum
2ae40 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2ae50 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20  ind_text64() is 
2ae60 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
2ae70 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73  * allowed values
2ae80 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72   shown above, or
2ae90 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63   if the text enc
2aea0 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
2aeb0 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65  nt.** from the e
2aec0 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
2aed0 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70  d by the sixth p
2aee0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
2aef0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69  he behavior.** i
2af00 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2af10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2af20 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
2af30 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
2af40 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
2af50 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
2af60 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
2af70 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
2af80 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
2af90 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
2afa0 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
2afb0 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
2afc0 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
2afd0 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
2afe0 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
2aff0 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
2b000 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
2b010 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
2b020 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
2b030 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
2b040 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
2b050 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
2b060 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
2b070 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
2b080 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
2b090 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
2b0a0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
2b0b0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
2b0c0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
2b0d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2b0e0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
2b0f0 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
2b100 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2b110 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2b120 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
2b130 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
2b140 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
2b150 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
2b160 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
2b170 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
2b180 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
2b190 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
2b1a0 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
2b1b0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
2b1c0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
2b1d0 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
2b1e0 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
2b1f0 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
2b200 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b210 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
2b220 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
2b230 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2b240 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2b250 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
2b260 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
2b270 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
2b280 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2b290 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
2b2a0 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
2b2b0 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
2b2c0 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
2b2d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b2e0 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
2b2f0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2b300 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
2b310 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
2b320 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
2b330 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
2b340 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20  [SQLITE_TOOBIG] 
2b350 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2b360 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66  d if the size of
2b370 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
2b380 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d  B.** exceeds lim
2b390 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b  its imposed by [
2b3a0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2b3b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2b3c0 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c  GTH]) or.** [SQL
2b3d0 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e  ITE_MAX_LENGTH].
2b3e0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
2b3f0 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
2b400 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2b410 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
2b420 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
2b430 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
2b440 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
2b450 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
2b460 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2b470 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b480 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
2b490 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2b4a0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2b4b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2b4c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2b4d0 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
2b4e0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2b4f0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2b500 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
2b510 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2b520 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
2b530 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2b540 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2b550 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2b560 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2b570 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
2b580 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2b590 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
2b5a0 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2b5b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2b5c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
2b5d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2b5e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2b5f0 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
2b600 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b610 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51  int, double);.SQ
2b620 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2b630 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2b640 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
2b650 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2b660 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
2b670 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2b680 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2b690 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
2b6a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
2b6b0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49  te3_int64);.SQLI
2b6c0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2b6d0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2b6e0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
2b6f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
2b700 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2b710 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2b720 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2b730 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2b740 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69  nt,const char*,i
2b750 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
2b760 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
2b770 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2b780 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  L sqlite3_bind_t
2b790 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2b7a0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2b7b0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2b7c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
2b7d0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2b7e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2b7f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73  e3_bind_text64(s
2b800 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b810 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
2b820 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
2b830 20 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 76 6f 69 64 28 2a 29           void(*)
2b850 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65  (void*), unsigne
2b860 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29  d char encoding)
2b870 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2b880 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2b890 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2b8a0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2b8b0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
2b8c0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2b8d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2b8e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2b8f0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2b900 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2b910 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 53 51   int, int n);.SQ
2b920 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2b930 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2b940 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2b950 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
2b960 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
2b970 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20  uint64);../*.** 
2b980 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2b990 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
2b9a0 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  rs.** METHOD: sq
2b9b0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2b9c0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
2b9d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
2b9e0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
2b9f0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
2ba00 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
2ba10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2ba20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
2ba30 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
2ba40 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
2ba50 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
2ba60 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
2ba70 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
2ba80 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
2ba90 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
2baa0 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
2bab0 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
2bac0 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
2bad0 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
2bae0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
2baf0 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
2bb00 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
2bb10 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
2bb20 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
2bb30 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
2bb40 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
2bb50 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
2bb60 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
2bb70 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2bb80 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
2bb90 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
2bba0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
2bbb0 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
2bbc0 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
2bbd0 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
2bbe0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
2bbf0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2bc00 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2bc10 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2bc20 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2bc30 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
2bc40 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2bc50 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2bc60 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2bc70 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2bc80 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2bc90 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2bca0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
2bcb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2bcc0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
2bcd0 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d  t Parameter.** M
2bce0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2bcf0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2bd00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2bd10 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
2bd20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2bd30 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
2bd40 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
2bd50 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
2bd60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2bd70 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
2bd80 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
2bd90 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
2bda0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
2bdb0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
2bdc0 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
2bdd0 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
2bde0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
2bdf0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
2be00 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
2be10 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
2be20 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
2be30 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
2be40 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
2be50 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
2be60 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
2be70 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
2be80 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
2be90 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
2bea0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
2beb0 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
2bec0 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
2bed0 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
2bee0 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
2bef0 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
2bf00 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
2bf10 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
2bf20 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
2bf30 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
2bf40 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
2bf50 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
2bf60 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
2bf70 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
2bf80 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
2bf90 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
2bfa0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2bfb0 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
2bfc0 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
2bfd0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
2bfe0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
2bff0 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
2c000 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
2c010 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
2c020 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
2c030 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2c040 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2c050 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2c060 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2c070 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2c080 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2c090 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2c0a0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2c0b0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2c0c0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2c0d0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2c0e0 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  st char *SQLITE_
2c0f0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2c100 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2c110 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2c120 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
2c130 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
2c140 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
2c150 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
2c160 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2c170 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2c180 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
2c190 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
2c1a0 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
2c1b0 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
2c1c0 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
2c1d0 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
2c1e0 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
2c1f0 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
2c200 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
2c210 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2c220 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
2c230 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
2c240 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
2c250 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
2c260 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
2c270 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
2c280 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
2c290 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
2c2a0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
2c2b0 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
2c2c0 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
2c2d0 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
2c2e0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2c2f0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2c300 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2c310 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2c320 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2c330 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2c340 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2c350 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2c360 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2c370 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2c380 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2c390 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2c3a0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2c3b0 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
2c3c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2c3d0 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
2c3e0 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
2c3f0 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
2c400 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2c410 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2c420 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2c430 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
2c440 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
2c450 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
2c460 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
2c470 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
2c480 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2c490 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
2c4a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c4b0 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
2c4c0 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
2c4d0 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
2c4e0 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
2c4f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2c500 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2c510 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
2c520 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2c530 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2c540 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2c550 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
2c560 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
2c570 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2c580 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
2c590 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2c5a0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2c5b0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
2c5c0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
2c5d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c5e0 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
2c5f0 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
2c600 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
2c610 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
2c620 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
2c630 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
2c640 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
2c650 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2c660 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2c670 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
2c680 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2c690 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2c6a0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
2c6b0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2c6c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c6d0 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
2c6e0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
2c6f0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2c700 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2c710 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
2c720 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
2c730 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
2c740 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
2c750 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
2c760 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
2c770 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
2c780 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2c790 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
2c7a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2c7b0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
2c7c0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
2c7d0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
2c7e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2c7f0 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
2c800 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2c810 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
2c820 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
2c830 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
2c840 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
2c850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c860 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
2c870 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
2c880 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
2c890 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2c8a0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
2c8b0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
2c8c0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2c8d0 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
2c8e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
2c8f0 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
2c900 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
2c910 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
2c920 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c930 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
2c940 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
2c950 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
2c960 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
2c970 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
2c980 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
2c990 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
2c9a0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2c9b0 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
2c9c0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
2c9d0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
2c9e0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
2c9f0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2ca00 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2ca10 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
2ca20 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
2ca30 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
2ca40 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
2ca50 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
2ca60 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
2ca70 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
2ca80 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
2ca90 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
2caa0 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
2cab0 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
2cac0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2cad0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2cae0 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
2caf0 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
2cb00 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
2cb10 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
2cb20 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
2cb30 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
2cb40 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
2cb50 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
2cb60 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
2cb70 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
2cb80 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
2cb90 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
2cba0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
2cbb0 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
2cbc0 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c  the next..*/.SQL
2cbd0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2cbe0 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
2cbf0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
2cc00 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2cc10 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51  tmt*, int N);.SQ
2cc20 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2cc30 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
2cc40 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2cc50 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
2cc60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2cc70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2cc80 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
2cc90 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
2cca0 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  lt.** METHOD: sq
2ccb0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2ccc0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2ccd0 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
2cce0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
2ccf0 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
2cd00 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
2cd10 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
2cd20 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
2cd30 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
2cd40 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
2cd50 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2cd60 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
2cd70 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
2cd80 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
2cd90 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
2cda0 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
2cdb0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
2cdc0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
2cdd0 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
2cde0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
2cdf0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
2ce00 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
2ce10 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2ce20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
2ce30 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
2ce40 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2ce50 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
2ce60 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2ce70 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
2ce80 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
2ce90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cea0 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
2ceb0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2cec0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2ced0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2cee0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2cef0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2cf00 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2cf10 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2cf20 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2cf30 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2cf40 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
2cf50 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2cf60 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
2cf70 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
2cf80 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
2cf90 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
2cfa0 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
2cfb0 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
2cfc0 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
2cfd0 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
2cfe0 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
2cff0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2d000 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
2d010 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
2d020 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2d030 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
2d040 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2d050 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2d060 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
2d070 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
2d080 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
2d090 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
2d0a0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
2d0b0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
2d0c0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
2d0d0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
2d0e0 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
2d0f0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
2d100 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2d110 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
2d120 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2d130 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
2d140 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
2d150 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
2d160 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
2d170 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
2d180 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
2d190 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
2d1a0 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
2d1b0 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
2d1c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2d1d0 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
2d1e0 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
2d1f0 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
2d200 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
2d210 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
2d220 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
2d230 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
2d240 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
2d250 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
2d260 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
2d270 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
2d280 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
2d290 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
2d2a0 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
2d2b0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2d2c0 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
2d2d0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
2d2e0 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
2d2f0 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
2d300 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
2d310 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
2d320 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
2d330 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
2d340 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
2d350 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
2d360 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
2d370 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2d380 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2d390 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
2d3a0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2d3b0 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
2d3c0 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
2d3d0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
2d3e0 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
2d3f0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2d400 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
2d410 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
2d420 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2d430 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2d440 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
2d450 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2d460 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
2d470 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
2d480 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
2d490 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
2d4a0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
2d4b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
2d4c0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2d4d0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2d4e0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2d4f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2d500 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
2d510 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d520 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2d530 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2d540 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2d550 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2d560 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
2d570 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2d580 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
2d590 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2d5a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2d5b0 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
2d5c0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d5d0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
2d5e0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2d5f0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2d600 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
2d610 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2d620 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2d630 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2d640 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2d650 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2d660 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
2d670 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
2d680 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
2d690 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2d6a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2d6b0 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
2d6c0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2d6d0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2d6e0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2d6f0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2d700 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
2d710 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
2d720 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2d730 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2d740 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  _stmt.**.** ^(Th
2d750 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2d760 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
2d770 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2d780 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
2d790 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
2d7a0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
2d7b0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2d7c0 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
2d7d0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
2d7e0 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
2d7f0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
2d800 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
2d810 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
2d820 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
2d830 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
2d840 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
2d850 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
2d860 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2d870 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2d880 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
2d890 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2d8a0 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
2d8b0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2d8c0 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
2d8d0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2d8e0 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
2d8f0 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
2d900 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
2d910 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
2d920 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
2d930 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
2d940 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
2d950 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
2d960 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
2d970 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
2d980 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
2d990 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
2d9a0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
2d9b0 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
2d9c0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
2d9d0 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
2d9e0 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
2d9f0 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
2da00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
2da10 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
2da20 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
2da30 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
2da40 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
2da50 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
2da60 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
2da70 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
2da80 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
2da90 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
2daa0 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
2dab0 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
2dac0 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
2dad0 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
2dae0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2daf0 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
2db00 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
2db10 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
2db20 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
2db30 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
2db40 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
2db50 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
2db60 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
2db70 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
2db80 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
2db90 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
2dba0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2dbb0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2dbc0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2dbd0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
2dbe0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2dbf0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2dc00 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  nst void *SQLITE
2dc10 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2dc20 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2dc30 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2dc40 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2dc50 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
2dc60 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2dc70 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2dc80 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2dc90 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
2dca0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
2dcb0 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
2dcc0 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
2dcd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2dce0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
2dcf0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2dd00 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
2dd10 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2dd20 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
2dd30 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
2dd40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2dd50 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
2dd60 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
2dd70 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
2dd80 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
2dd90 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
2dda0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
2ddb0 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
2ddc0 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
2ddd0 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
2dde0 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
2ddf0 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
2de00 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
2de10 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
2de20 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
2de30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2de40 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
2de50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2de60 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
2de70 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
2de80 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
2de90 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
2dea0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2deb0 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
2dec0 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
2ded0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
2dee0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
2def0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
2df00 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
2df10 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
2df20 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
2df30 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
2df40 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
2df50 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
2df60 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
2df70 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
2df80 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
2df90 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
2dfa0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
2dfb0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
2dfc0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
2dfd0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
2dfe0 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
2dff0 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
2e000 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
2e010 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
2e020 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
2e030 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
2e040 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
2e050 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
2e060 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
2e070 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
2e080 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
2e090 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2e0a0 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
2e0b0 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
2e0c0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2e0d0 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
2e0e0 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
2e0f0 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
2e100 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
2e110 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
2e120 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
2e130 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
2e140 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
2e150 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
2e160 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a  urs within an.**
2e170 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2e180 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
2e190 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
2e1a0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
2e1b0 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
2e1c0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ing..**.** ^[SQL
2e1d0 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
2e1e0 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
2e1f0 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
2e200 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
2e210 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
2e220 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2e230 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2e240 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
2e250 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
2e260 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
2e270 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2e280 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
2e290 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
2e2a0 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
2e2b0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
2e2c0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te..**.** ^If th
2e2d0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2e2e0 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
2e2f0 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
2e300 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
2e310 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
2e320 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
2e330 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
2e340 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
2e350 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
2e360 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
2e370 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
2e380 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
2e390 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2e3a0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
2e3b0 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
2e3c0 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
2e3d0 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
2e3e0 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
2e3f0 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  * ^[SQLITE_ERROR
2e400 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
2e410 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
2e420 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
2e430 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
2e440 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
2e450 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2e460 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2e470 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
2e480 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
2e490 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
2e4a0 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
2e4b0 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
2e4c0 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  g()]..** ^With t
2e4d0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2e4e0 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
2e4f0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2e500 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
2e510 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
2e520 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
2e530 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
2e540 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
2e550 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
2e560 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
2e570 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2e580 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
2e590 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e5a0 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22  ent].  ^In the "
2e5b0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
2e5c0 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
2e5d0 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
2e5e0 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
2e5f0 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
2e600 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
2e610 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
2e620 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
2e630 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
2e640 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
2e650 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
2e660 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
2e670 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2e680 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
2e690 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
2e6a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2e6b0 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
2e6c0 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
2e6d0 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
2e6e0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2e6f0 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
2e700 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
2e710 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
2e720 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
2e730 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
2e740 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
2e750 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
2e760 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
2e770 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
2e780 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
2e790 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69  ** For all versi
2e7a0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70  ons of SQLite up
2e7b0 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e   to and includin
2e7c0 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61  g 3.6.23.1, a ca
2e7d0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2e7e0 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72  3_reset()] was r
2e7f0 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71  equired after sq
2e800 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74  lite3_step() ret
2e810 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a  urned anything.*
2e820 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  * other than [SQ
2e830 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65  LITE_ROW] before
2e840 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
2e850 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
2e860 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2e870 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73    Failure to res
2e880 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
2e890 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
2e8a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2e8b0 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75  et()] would resu
2e8c0 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  lt in an [SQLITE
2e8d0 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20  _MISUSE] return 
2e8e0 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
2e8f0 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74  step().  But aft
2e900 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32  er version 3.6.2
2e910 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  3.1, sqlite3_ste
2e920 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
2e930 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2e940 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
2e950 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
2e960 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
2e970 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
2e980 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
2e990 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
2e9a0 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
2e9b0 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
2e9c0 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
2e9d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
2e9e0 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
2e9f0 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
2ea00 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
2ea10 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
2ea20 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
2ea30 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
2ea40 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2ea50 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
2ea60 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
2ea70 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
2ea80 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
2ea90 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
2eaa0 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
2eab0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2eac0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2ead0 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
2eae0 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
2eaf0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
2eb00 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
2eb10 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
2eb20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
2eb30 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
2eb40 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
2eb50 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
2eb60 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
2eb70 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
2eb80 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2eb90 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
2eba0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
2ebb0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2ebc0 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
2ebd0 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
2ebe0 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
2ebf0 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
2ec00 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
2ec10 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
2ec20 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
2ec30 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2ec40 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
2ec50 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
2ec60 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
2ec70 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
2ec80 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
2ec90 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2eca0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2ecb0 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
2ecc0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
2ecd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2ece0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2ecf0 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
2ed00 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
2ed10 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
2ed20 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2ed30 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
2ed40 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
2ed50 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
2ed60 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
2ed70 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2ed80 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53  ecommended..*/.S
2ed90 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2eda0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2edb0 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
2edc0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2edd0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2ede0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2edf0 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20  a result set.** 
2ee00 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2ee10 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2ee20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2ee30 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
2ee40 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2ee50 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2ee60 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
2ee70 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2ee80 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
2ee90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2eea0 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
2eeb0 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
2eec0 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
2eed0 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
2eee0 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
2eef0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2ef00 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
2ef10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
2ef20 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
2ef30 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
2ef40 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2ef50 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
2ef60 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2ef70 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2ef80 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
2ef90 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
2efa0 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
2efb0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2efc0 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
2efd0 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
2efe0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
2eff0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
2f000 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
2f010 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
2f020 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2f030 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
2f040 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
2f050 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
2f060 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2f070 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
2f080 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
2f090 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
2f0a0 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
2f0b0 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
2f0c0 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
2f0d0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
2f0e0 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
2f0f0 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
2f100 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
2f110 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
2f120 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
2f130 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2f140 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2f150 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
2f160 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2f170 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2f180 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
2f190 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2f1a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f1b0 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
2f1c0 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
2f1d0 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
2f1e0 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
2f1f0 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
2f200 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
2f210 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
2f220 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
2f230 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2f240 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2f250 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
2f260 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
2f270 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
2f280 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
2f290 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
2f2a0 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
2f2b0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2f2c0 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
2f2d0 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
2f2e0 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
2f2f0 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
2f300 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
2f310 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
2f320 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2f330 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
2f340 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
2f350 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
2f360 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
2f370 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
2f380 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
2f390 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
2f3a0 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
2f3b0 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
2f3c0 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
2f3d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2f3e0 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
2f3f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
2f400 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
2f410 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
2f420 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f430 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
2f440 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
2f450 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
2f460 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
2f470 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
2f480 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
2f490 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
2f4a0 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
2f4b0 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
2f4c0 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
2f4d0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
2f4e0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2f4f0 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
2f500 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2f510 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2f520 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
2f530 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
2f540 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
2f550 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
2f560 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
2f570 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
2f580 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
2f590 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
2f5a0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
2f5b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2f5c0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
2f5d0 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
2f5e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2f5f0 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
2f600 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
2f610 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2f620 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
2f630 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
2f640 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
2f650 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2f660 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
2f670 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
2f680 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
2f690 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
2f6a0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2f6b0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2f6c0 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
2f6d0 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
2f6e0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2f6f0 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2f700 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
2f710 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2f720 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2f730 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
2f740 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2f750 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
2f760 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
2f770 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
2f780 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
2f790 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2f7a0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
2f7b0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2f7c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2f7d0 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
2f7e0 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
2f7f0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
2f800 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2f810 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
2f820 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
2f830 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
2f840 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
2f850 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2f860 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
2f870 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
2f880 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
2f890 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2f8a0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
2f8b0 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
2f8c0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2f8d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2f8e0 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
2f8f0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2f900 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
2f910 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
2f920 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
2f930 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2f940 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
2f950 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2f960 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2f970 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2f980 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
2f990 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
2f9a0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
2f9b0 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
2f9c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2f9d0 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
2f9e0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2f9f0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2fa00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fa10 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
2fa20 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2fa30 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
2fa40 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2fa50 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
2fa60 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
2fa70 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
2fa80 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
2fa90 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
2faa0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2fab0 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
2fac0 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
2fad0 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
2fae0 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
2faf0 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
2fb00 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
2fb10 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2fb20 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
2fb30 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
2fb40 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
2fb50 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
2fb60 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
2fb70 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
2fb80 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
2fb90 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
2fba0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
2fbb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2fbc0 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
2fbd0 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
2fbe0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2fbf0 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
2fc00 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
2fc10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2fc20 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
2fc30 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2fc40 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
2fc50 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2fc60 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
2fc70 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2fc80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2fc90 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2fca0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2fcb0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2fcc0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2fcd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2fce0 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
2fcf0 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2fd00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2fd10 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2fd20 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2fd30 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
2fd40 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2fd50 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2fd60 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2fd70 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2fd80 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2fd90 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
2fda0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
2fdb0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
2fdc0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
2fdd0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
2fde0 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2fdf0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2fe00 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2fe10 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2fe20 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2fe30 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2fe40 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73  _bytes() returns
2fe50 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   zero..**.** ^If
2fe60 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2fe70 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20   BLOB or UTF-16 
2fe80 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2fe90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fea0 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74  ytes16().** rout
2feb0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2fec0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2fed0 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2fee0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2fef0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2ff00 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65  TF-8 string, the
2ff10 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2ff20 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65  _bytes16() conve
2ff30 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
2ff40 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20  g to UTF-16 and 
2ff50 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2ff60 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2ff70 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2ff80 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2ff90 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2ffa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ffb0 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  16() uses.** [sq
2ffc0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2ffd0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
2ffe0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
2fff0 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72  -16 string and r
30000 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
30010 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
30020 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
30030 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
30040 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
30050 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30060 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a  es16() returns z
30070 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ero..**.** ^The 
30080 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
30090 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
300a0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
300b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
300c0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64  umn_bytes16()] d
300d0 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  o not include th
300e0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
300f0 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  rs at the end.**
30100 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
30110 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
30120 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
30130 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
30140 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
30150 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
30160 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
30170 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20   are the number 
30180 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
30190 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
301a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
301b0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
301c0 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
301d0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
301e0 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
301f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30200 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
30210 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
30220 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  e always zero-te
30230 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
30240 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
30250 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
30260 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
30270 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
30280 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  B is a NULL poin
30290 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61  ter..**.** <b>Wa
302a0 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20  rning:</b> ^The 
302b0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
302c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
302d0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
302e0 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
302f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30300 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d   object.  In a m
30310 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e 76  ultithreaded env
30320 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20  ironment,.** an 
30330 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
30340 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
30350 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
30360 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a  d safely with.**
30370 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
30380 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
30390 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
303a0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
303b0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
303c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
303d0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
303e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
303f0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
30400 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
30410 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
30420 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
30430 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
30440 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
30450 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30460 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
30470 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
30480 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76  es()], the behav
30490 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ior is not threa
304a0 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dsafe..**.** The
304b0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
304c0 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
304d0 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
304e0 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
304f0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
30500 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
30510 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
30520 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
30530 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
30540 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
30550 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
30560 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
30570 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
30580 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
30590 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
305a0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
305b0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
305c0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
305d0 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
305e0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
305f0 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
30600 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
30610 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
30620 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
30630 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
30640 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
30650 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
30660 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
30670 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
30680 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
30690 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
306a0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
306b0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
306c0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
306d0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
306e0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
306f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
30700 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
30710 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
30720 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
30730 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
30740 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
30750 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
30760 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
30770 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
30780 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
30790 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
307a0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
307b0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
307c0 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
307d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
307e0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
307f0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
30800 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
30810 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
30820 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
30830 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
30840 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
30850 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
30860 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
30870 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
30880 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
30890 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
308a0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
308b0 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  B    <td> [CAST]
308c0 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e   to BLOB.** <tr>
308d0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
308e0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
308f0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
30900 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
30910 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
30920 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
30930 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
30940 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
30950 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
30960 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
30970 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
30980 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
30990 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
309a0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
309b0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
309c0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
309d0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
309e0 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  L.** <tr><td>  B
309f0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
30a00 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
30a10 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
30a20 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
30a30 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
30a40 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
30a50 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
30a60 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
30a70 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
30a80 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
30a90 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
30aa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
30ab0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
30ac0 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
30ad0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
30ae0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
30af0 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
30b00 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
30b10 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
30b20 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
30b30 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
30b40 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
30b50 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
30b60 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
30b70 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
30b80 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
30b90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
30ba0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
30bb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30bc0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
30bd0 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
30be0 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
30bf0 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
30c00 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
30c10 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
30c20 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
30c30 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
30c40 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
30c50 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
30c60 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
30c70 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
30c80 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
30c90 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
30ca0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
30cb0 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
30cc0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
30cd0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
30ce0 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
30cf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30d00 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
30d10 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
30d20 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
30d30 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
30d40 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
30d50 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
30d60 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
30d70 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  l>.**.** ^Conver
30d80 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
30d90 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
30da0 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
30db0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
30dc0 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
30dd0 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
30de0 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
30df0 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
30e00 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
30e10 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
30e20 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65  ior pointer refe
30e30 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65  rences will have
30e40 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
30e50 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
30e60 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
30e70 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
30e80 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
30e90 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
30ea0 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
30eb0 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
30ec0 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
30ed0 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
30ee0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
30ef0 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
30f00 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
30f10 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
30f20 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
30f30 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
30f40 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
30f50 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
30f60 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
30f70 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
30f80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
30f90 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
30fa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
30fb0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
30fc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30fd0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
30fe0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
30ff0 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
31000 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
31010 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
31020 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
31030 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
31040 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
31050 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
31060 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
31070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
31080 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
31090 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
310a0 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
310b0 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
310c0 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
310d0 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
310e0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
310f0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
31100 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31110 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
31120 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
31130 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
31140 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
31150 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
31160 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
31170 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
31180 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
31190 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
311a0 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
311b0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
311c0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
311d0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
311e0 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
311f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
31200 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
31210 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
31220 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
31230 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
31240 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
31250 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
31260 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
31270 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
31280 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
31290 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
312a0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
312b0 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
312c0 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
312d0 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
312e0 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
312f0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
31300 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65  .  Do <em>not</e
31310 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  m> pass the poin
31320 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
31330 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
31340 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
31350 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
31360 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
31370 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
31380 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
31390 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
313a0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
313b0 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
313c0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
313d0 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
313e0 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
313f0 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
31400 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
31410 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
31420 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
31430 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
31440 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
31450 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
31460 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
31470 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
31480 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
31490 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
314a0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
314b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
314c0 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
314d0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
314e0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
314f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31500 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
31510 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
31520 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
31530 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
31540 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
31550 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
31560 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
31570 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
31580 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
31590 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
315a0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64  l);.SQLITE_API d
315b0 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44  ouble SQLITE_STD
315c0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
315d0 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
315e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
315f0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
31600 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
31610 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
31620 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
31630 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
31640 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
31650 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f  e3_int64 SQLITE_
31660 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
31670 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
31680 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
31690 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
316a0 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  I const unsigned
316b0 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
316c0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
316d0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
316e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
316f0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  l);.SQLITE_API c
31700 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
31710 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
31720 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
31730 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31740 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
31750 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
31760 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
31770 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
31780 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
31790 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
317a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
317b0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
317c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
317d0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
317e0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
317f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
31800 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
31810 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
31820 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52  ct.** DESTRUCTOR
31830 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31840 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31850 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
31860 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
31870 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
31880 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31890 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
318a0 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
318b0 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
318c0 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
318d0 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
318e0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
318f0 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
31900 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
31910 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31920 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
31930 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
31940 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
31950 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
31960 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
31970 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
31980 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
31990 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
319a0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
319b0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
319c0 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
319d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
319e0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
319f0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
31a00 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
31a10 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
31a20 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
31a30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31a40 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
31a50 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
31a60 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
31a70 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
31a80 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
31a90 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
31aa0 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
31ab0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
31ac0 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
31ad0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
31ae0 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
31af0 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
31b00 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
31b10 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
31b20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
31b30 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
31b40 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
31b50 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
31b60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
31b70 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
31b80 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
31b90 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
31ba0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
31bb0 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
31bc0 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
31bd0 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
31be0 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
31bf0 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
31c00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
31c10 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
31c20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
31c30 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
31c40 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
31c50 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
31c60 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
31c70 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
31c80 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
31c90 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
31ca0 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
31cb0 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
31cc0 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
31cd0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
31ce0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66  TDCALL sqlite3_f
31cf0 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
31d00 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
31d10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
31d20 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
31d30 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
31d40 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31d50 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54  te3_stmt.**.** T
31d60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
31d70 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
31d80 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
31d90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31da0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
31db0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
31dc0 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
31dd0 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
31de0 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
31df0 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
31e00 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
31e10 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
31e20 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
31e30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
31e40 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
31e50 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
31e60 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
31e70 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
31e80 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
31e90 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
31ea0 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
31eb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
31ec0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
31ed0 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
31ee0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31ef0 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
31f00 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
31f10 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
31f20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
31f30 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
31f40 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
31f50 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
31f60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
31f70 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
31f80 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
31f90 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
31fa0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
31fb0 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
31fc0 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
31fd0 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
31fe0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
31ff0 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
32000 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
32010 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
32020 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
32030 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
32040 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
32050 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
32060 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
32070 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
32080 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
32090 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
320a0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
320b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
320c0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
320d0 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
320e0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
320f0 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
32100 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
32110 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
32120 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
32130 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c  ement] S..*/.SQL
32140 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
32150 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
32160 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
32170 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
32180 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32190 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
321a0 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
321b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
321c0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
321d0 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
321e0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
321f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
32200 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
32210 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
32220 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
32230 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
32240 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
32250 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
32260 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
32270 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
32280 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
32290 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
322a0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
322b0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
322c0 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
322d0 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
322e0 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
322f0 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
32300 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
32310 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
32320 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
32330 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
32340 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
32350 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
32360 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
32370 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
32380 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
32390 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
323a0 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
323b0 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
323c0 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
323d0 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
323e0 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
323f0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
32400 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
32410 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
32420 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
32430 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
32440 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
32450 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
32460 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
32470 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
32480 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
32490 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
324a0 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
324b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
324c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
324d0 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
324e0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
324f0 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
32500 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
32510 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
32520 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
32530 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32540 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
32550 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
32560 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
32570 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
32580 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
32590 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
325a0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
325b0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
325c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
325d0 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
325e0 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
325f0 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
32600 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
32610 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
32620 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
32630 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
32640 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
32650 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
32660 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
32670 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
32680 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
32690 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
326a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
326b0 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
326c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
326d0 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
326e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
326f0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
32700 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
32710 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
32720 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
32730 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
32740 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
32750 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
32760 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
32770 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
32780 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
32790 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
327a0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
327b0 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
327c0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
327d0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
327e0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
327f0 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
32800 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
32810 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
32820 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
32830 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
32840 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
32850 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
32860 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
32870 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
32880 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
32890 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
328a0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
328b0 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20  should set this 
328c0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
328d0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
328e0 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   if the function
328f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32900 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c  invokes .** [sql
32910 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
32920 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6le()] on an inp
32930 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ut, or [SQLITE_U
32940 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a  TF16BE] if the.*
32950 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
32960 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65   invokes [sqlite
32970 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
32980 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
32990 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   or.** [SQLITE_U
329a0 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65  TF16] if [sqlite
329b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
329c0 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53  ] is used, or [S
329d0 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f  QLITE_UTF8].** o
329e0 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20  therwise.  ^The 
329f0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
32a00 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
32a10 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
32a20 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66  es using.** diff
32a30 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20  erent preferred 
32a40 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20  text encodings, 
32a50 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69  with different i
32a60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
32a70 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64  or.** each encod
32a80 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75  ing..** ^When mu
32a90 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
32aa0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
32ab0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
32ac0 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
32ad0 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
32ae0 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
32af0 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
32b00 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
32b10 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
32b20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
32b30 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e  meter may option
32b40 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74  ally be ORed wit
32b50 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  h [SQLITE_DETERM
32b60 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73  INISTIC].** to s
32b70 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66  ignal that the f
32b80 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77  unction will alw
32b90 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
32ba0 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e  ame result given
32bb0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70  .** the same inp
32bc0 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e  uts within a sin
32bd0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
32be0 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e  t.  Most SQL fun
32bf0 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65  ctions are.** de
32c00 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
32c10 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64  e built-in [rand
32c20 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  om()] SQL functi
32c30 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  on is an example
32c40 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   of a.** functio
32c50 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65  n that is not de
32c60 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
32c70 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70  e SQLite query p
32c80 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74  lanner is able t
32c90 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64  o.** perform add
32ca0 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61  itional optimiza
32cb0 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69  tions on determi
32cc0 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73  nistic functions
32cd0 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74  , so use.** of t
32ce0 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  he [SQLITE_DETER
32cf0 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69  MINISTIC] flag i
32d00 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68  s recommended wh
32d10 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a  ere possible..**
32d20 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
32d30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
32d40 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
32d50 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
32d60 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
32d70 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
32d80 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
32d90 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
32da0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
32db0 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
32dc0 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
32dd0 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
32de0 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
32df0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
32e00 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
32e10 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
32e20 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
32e30 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
32e40 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
32e50 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
32e60 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
32e70 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
32e80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
32e90 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
32ea0 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
32eb0 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
32ec0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
32ed0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
32ee0 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
32ef0 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
32f00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
32f10 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
32f20 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
32f30 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
32f40 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
32f50 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
32f60 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
32f70 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
32f80 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
32f90 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
32fa0 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
32fb0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
32fc0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
32fd0 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
32fe0 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
32ff0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
33000 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
33010 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
33020 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
33030 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
33040 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
33050 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
33060 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
33070 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
33080 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
33090 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
330a0 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
330b0 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
330c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
330d0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
330e0 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
330f0 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
33100 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
33110 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
33120 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
33130 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
33140 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
33150 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
33160 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
33170 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
33180 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
33190 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
331a0 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
331b0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
331c0 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
331d0 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
331e0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
331f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
33200 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
33210 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
33220 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
33230 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
33240 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
33250 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
33260 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
33270 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
33280 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
33290 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
332a0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
332b0 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
332c0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
332d0 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
332e0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
332f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
33300 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
33310 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
33320 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
33330 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
33340 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
33350 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33360 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
33370 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
33380 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
33390 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
333a0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
333b0 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
333c0 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
333d0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
333e0 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
333f0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
33400 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
33410 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
33420 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
33430 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
33440 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
33450 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
33460 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
33470 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
33480 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
33490 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
334a0 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
334b0 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
334c0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
334d0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
334e0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
334f0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
33500 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
33510 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
33520 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
33530 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
33540 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
33550 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33560 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
33570 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33580 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
33590 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
335a0 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
335b0 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
335c0 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
335d0 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
335e0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
335f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
33600 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
33610 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
33620 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
33630 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
33640 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
33650 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
33660 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
33670 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33680 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
33690 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
336a0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
336b0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
336c0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
336d0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
336e0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
336f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33700 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
33710 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
33720 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
33730 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
33740 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
33750 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
33760 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
33770 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
33780 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
33790 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  L sqlite3_create
337a0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
337b0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
337c0 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
337d0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
337e0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
337f0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
33800 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
33810 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
33820 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
33830 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
33840 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
33850 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
33860 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
33870 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
33880 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
33890 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  t*).);.SQLITE_AP
338a0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
338b0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65  CALL sqlite3_cre
338c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
338d0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
338e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
338f0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
33900 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
33910 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
33920 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
33930 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
33940 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
33950 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
33960 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
33970 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
33980 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
33990 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
339a0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
339b0 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28  ntext*),.  void(
339c0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
339d0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
339e0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
339f0 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
33a00 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
33a10 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
33a20 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
33a30 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
33a40 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
33a50 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
33a60 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
33a70 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
33a80 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    1    /* IMP: R
33a90 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a  -37514-35566 */.
33aa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
33ab0 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 20  TF16LE        2 
33ac0 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33     /* IMP: R-033
33ad0 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66  71-37637 */.#def
33ae0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
33af0 42 45 20 20 20 20 20 20 20 20 33 20 20 20 20 2f  BE        3    /
33b00 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33  * IMP: R-51971-3
33b10 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20  4154 */.#define 
33b20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
33b30 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
33b40 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
33b50 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
33b60 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
33b70 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70       5    /* Dep
33b80 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69  recated */.#defi
33b90 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
33ba0 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
33bb0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33bc0 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
33bd0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
33be0 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67  F: Function Flag
33bf0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
33c00 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f  nstants may be O
33c10 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74  Red together wit
33c20 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
33c30 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72  E_UTF8 | preferr
33c40 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
33c50 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  ] as the fourth 
33c60 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
33c70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33c80 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  unction()], [sql
33c90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33ca0 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
33cb0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33cc0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e  _function_v2()].
33cd0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
33ce0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
33cf0 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a      0x800../*.**
33d00 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
33d10 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a  cated Functions.
33d20 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
33d30 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
33d40 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61  ons are [depreca
33d50 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20  ted].  In order 
33d60 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
33d70 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
33d80 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
33d90 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75  r code, these fu
33da0 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  nctions continue
33db0 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f   .** to be suppo
33dc0 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20  rted.  However, 
33dd0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
33de0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
33df0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
33e00 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
33e10 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72   encourage progr
33e20 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a  ammers to avoid.
33e30 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ** these functio
33e40 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20  ns, we will not 
33e50 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65  explain what the
33e60 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
33e70 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
33e80 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41  RECATED.SQLITE_A
33e90 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
33ea0 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f  ATED int SQLITE_
33eb0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
33ec0 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
33ed0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33ee0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
33ef0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
33f00 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
33f10 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  LL sqlite3_expir
33f20 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
33f30 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
33f40 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
33f50 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
33f60 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  LL sqlite3_trans
33f70 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
33f80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
33f90 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
33fa0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
33fb0 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c  PRECATED int SQL
33fc0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
33fd0 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
33fe0 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
33ff0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
34000 45 43 41 54 45 44 20 76 6f 69 64 20 53 51 4c 49  ECATED void SQLI
34010 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
34020 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
34030 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
34040 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
34050 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45  CATED int SQLITE
34060 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
34070 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
34080 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
34090 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a  te3_int64,int),.
340a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
340b0 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69        void*,sqli
340c0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
340d0 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
340e0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
340f0 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
34100 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
34110 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  e.**.** The C-la
34120 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
34130 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
34140 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
34150 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
34160 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
34170 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
34180 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
34190 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
341a0 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
341b0 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a  r aggregate.  .*
341c0 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
341d0 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
341e0 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
341f0 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
34200 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
34210 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34220 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
34230 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34240 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
34250 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
34260 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
34270 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
34280 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
34290 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
342a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
342b0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
342c0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
342d0 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
342e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
342f0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
34300 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
34310 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34320 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
34330 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
34340 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
34350 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
34360 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
34370 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
34380 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
34390 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
343a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
343b0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
343c0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
343d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
343e0 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
343f0 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
34400 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
34410 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
34420 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
34430 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
34440 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
34450 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
34460 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
34470 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
34480 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
34490 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
344a0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
344b0 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e  hat these routin
344c0 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
344d0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
344e0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
344f0 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
34500 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
34510 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
34520 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
34530 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
34540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34550 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
34560 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
34570 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
34580 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
34590 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
345a0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
345b0 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
345c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
345d0 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
345e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
345f0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
34600 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
34610 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
34620 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
34630 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
34640 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
34650 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
34660 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
34670 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
34680 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
34690 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
346a0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
346b0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
346c0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
346d0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
346e0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
346f0 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
34700 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
34710 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
34720 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
34730 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
34740 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
34750 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
34760 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
34770 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
34780 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
34790 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
347a0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
347b0 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
347c0 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
347d0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
347e0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
347f0 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
34800 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
34810 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
34820 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
34830 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
34840 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
34850 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
34860 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
34870 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34880 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
34890 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
348a0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
348b0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
348c0 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
348d0 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
348e0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
348f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
34900 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
34910 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
34920 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
34930 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
34940 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
34950 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
34960 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
34970 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
34980 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
34990 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
349a0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
349b0 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
349c0 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
349d0 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49  ameters..*/.SQLI
349e0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
349f0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
34a00 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
34a10 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c  blob(sqlite3_val
34a20 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
34a30 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
34a40 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
34a50 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
34a60 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
34a70 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
34a80 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
34a90 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
34aa0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
34ab0 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20  LITE_API double 
34ac0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
34ad0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
34ae0 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
34af0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
34b00 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
34b10 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
34b20 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
34b30 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
34b40 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53   sqlite3_int64 S
34b50 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
34b60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
34b70 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
34b80 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
34b90 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
34ba0 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
34bb0 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
34bc0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
34bd0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
34be0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
34bf0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
34c00 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
34c10 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34c20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
34c30 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
34c40 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
34c50 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
34c60 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34c70 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
34c80 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
34c90 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
34ca0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
34cb0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
34cc0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
34cd0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
34ce0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
34cf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34d00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
34d10 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
34d20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
34d30 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
34d40 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
34d50 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 69   CAPI3REF: Findi
34d60 6e 67 20 54 68 65 20 53 75 62 74 79 70 65 20 4f  ng The Subtype O
34d70 66 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20  f SQL Values.** 
34d80 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
34d90 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  value.**.** The 
34da0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75  sqlite3_value_su
34db0 62 74 79 70 65 28 56 29 20 66 75 6e 63 74 69 6f  btype(V) functio
34dc0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 75  n returns the su
34dd0 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20 61 6e 20  btype for.** an 
34de0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
34df0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
34e00 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56 2e 20 20  n] argument V.  
34e10 54 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 69  The subtype.** i
34e20 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61 6e 20 62  nformation can b
34e30 65 20 75 73 65 64 20 74 6f 20 70 61 73 73 20 61  e used to pass a
34e40 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75 6e 74 20   limited amount 
34e50 6f 66 20 63 6f 6e 74 65 78 74 20 66 72 6f 6d 0a  of context from.
34e60 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75 6e 63 74  ** one SQL funct
34e70 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65 72 2e 20  ion to another. 
34e80 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
34e90 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65  3_result_subtype
34ea0 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  ()].** routine t
34eb0 6f 20 73 65 74 20 74 68 65 20 73 75 62 74 79 70  o set the subtyp
34ec0 65 20 66 6f 72 20 74 68 65 20 72 65 74 75 72 6e  e for the return
34ed0 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c   value of an SQL
34ee0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
34ef0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 6e 6f   SQLite makes no
34f00 20 75 73 65 20 6f 66 20 73 75 62 74 79 70 65 20   use of subtype 
34f10 69 74 73 65 6c 66 2e 20 20 49 74 20 6d 65 72 65  itself.  It mere
34f20 6c 79 20 70 61 73 73 65 73 20 74 68 65 20 73 75  ly passes the su
34f30 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 74 68  btype.** from th
34f40 65 20 72 65 73 75 6c 74 20 6f 66 20 6f 6e 65 20  e result of one 
34f50 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
34f60 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
34f70 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  n] into the.** i
34f80 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68 65 72 2e  nput of another.
34f90 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 75  .*/.SQLITE_API u
34fa0 6e 73 69 67 6e 65 64 20 69 6e 74 20 53 51 4c 49  nsigned int SQLI
34fb0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
34fc0 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65  e3_value_subtype
34fd0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34fe0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34ff0 46 3a 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65  F: Copy And Free
35000 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d   SQL Values.** M
35010 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76  ETHOD: sqlite3_v
35020 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  alue.**.** ^The 
35030 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
35040 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d  p(V) interface m
35050 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
35060 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
35070 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61  e].** object D a
35080 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
35090 6e 74 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70  nter to that cop
350a0 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  y.  ^The [sqlite
350b0 33 5f 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65  3_value] returne
350c0 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65  d.** is a [prote
350d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
350e0 75 65 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20  ue] object even 
350f0 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
35100 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  not..** ^The sql
35110 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56  ite3_value_dup(V
35120 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
35130 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73  rns NULL if V is
35140 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a   NULL or if a.**
35150 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
35160 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  on fails..**.** 
35170 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
35180 75 65 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72  ue_free(V) inter
35190 66 61 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73  face frees an [s
351a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
351b0 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73  ject.** previous
351c0 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
351d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
351e0 64 75 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69  dup()].  ^If V i
351f0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
35200 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
35210 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69  _value_free(V) i
35220 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
35230 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  op..*/.SQLITE_AP
35240 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  I SQLITE_EXPERIM
35250 45 4e 54 41 4c 20 73 71 6c 69 74 65 33 5f 76 61  ENTAL sqlite3_va
35260 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  lue *SQLITE_STDC
35270 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
35280 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69  e_dup(const sqli
35290 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
352a0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45  ITE_API SQLITE_E
352b0 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
352c0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
352d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72  sqlite3_value_fr
352e0 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ee(sqlite3_value
352f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
35300 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
35310 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
35320 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44  ontext.** METHOD
35330 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
35340 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
35350 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
35360 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
35370 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
35380 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
35390 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
353a0 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
353b0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
353c0 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
353d0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
353e0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
353f0 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
35400 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
35410 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
35420 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
35430 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
35440 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
35450 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
35460 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
35470 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
35480 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
35490 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
354a0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
354b0 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
354c0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
354d0 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
354e0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
354f0 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
35500 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
35510 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
35520 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
35530 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
35540 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
35550 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
35560 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
35570 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
35580 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
35590 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
355a0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
355b0 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
355c0 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
355d0 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
355e0 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
355f0 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
35600 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
35610 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
35620 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
35630 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
35640 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
35650 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
35660 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
35670 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
35680 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
35690 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
356a0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
356b0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
356c0 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
356d0 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
356e0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
356f0 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
35700 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
35710 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74  r .** when first
35720 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20   called if N is 
35730 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
35740 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66  al to zero or if
35750 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c   a memory.** all
35760 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75  ocate error occu
35770 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  rs..**.** ^(The 
35780 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20  amount of space 
35790 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
357a0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
357b0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a  ontext(C,N) is.*
357c0 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  * determined by 
357d0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
357e0 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73  on first success
357f0 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67  ful call.  Chang
35800 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65  ing the.** value
35810 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75   of N in subsequ
35820 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
35830 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
35840 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a  ntext() within.*
35850 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  * the same aggre
35860 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
35870 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20  stance will not 
35880 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  resize the memor
35890 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  y.** allocation.
358a0 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 78  )^  Within the x
358b0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20  Final callback, 
358c0 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20  it is customary 
358d0 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e  to set.** N=0 in
358e0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
358f0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35900 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74  ext(C,N) so that
35910 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73   no .** pointles
35920 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
35930 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a  ions occur..**.*
35940 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  * ^SQLite automa
35950 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
35960 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
35970 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
35980 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35990 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61  ext() when the a
359a0 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63  ggregate query c
359b0 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
359c0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
359d0 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f  ter must be a co
359e0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
359f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
35a00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
35a10 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
35a20 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
35a30 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65  r.** to the xSte
35a40 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  p or xFinal call
35a50 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
35a60 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
35a70 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
35a80 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
35a90 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
35aa0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
35ab0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
35ac0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
35ad0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
35ae0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
35af0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
35b00 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
35b10 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67 67  CALL sqlite3_agg
35b20 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
35b30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35b40 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
35b50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
35b60 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
35b70 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
35b80 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
35b90 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
35ba0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
35bb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
35bc0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
35bd0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
35be0 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
35bf0 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
35c00 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
35c10 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
35c20 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35c30 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
35c40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35c50 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
35c60 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
35c70 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
35c80 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
35c90 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
35ca0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
35cb0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
35cc0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
35cd0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
35ce0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
35cf0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35d00 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
35d10 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
35d20 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  PI void *SQLITE_
35d30 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
35d40 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
35d50 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
35d60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
35d70 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
35d80 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  n For Functions.
35d90 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
35da0 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
35db0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
35dc0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
35dd0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
35de0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
35df0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
35e00 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35e10 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
35e20 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
35e30 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
35e40 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35e50 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
35e60 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35e70 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
35e80 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
35e90 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
35ea0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
35eb0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35ec0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
35ed0 73 71 6c 69 74 65 33 20 2a 53 51 4c 49 54 45 5f  sqlite3 *SQLITE_
35ee0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
35ef0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
35f00 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
35f10 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
35f20 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
35f30 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a  uxiliary Data.**
35f40 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
35f50 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54  _context.**.** T
35f60 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d  hese functions m
35f70 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e  ay be used by (n
35f80 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51  on-aggregate) SQ
35f90 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
35fa0 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
35fb0 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
35fc0 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
35fd0 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
35fe0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
35ff0 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
36000 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
36010 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
36020 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
36030 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
36040 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
36050 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
36060 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  tadata may be pr
36070 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61  eserved.  An exa
36080 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65  mple.** of where
36090 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75   this might be u
360a0 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65  seful is in a re
360b0 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
360c0 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e   matching.** fun
360d0 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
360e0 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
360f0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
36100 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f  ssion can be sto
36110 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
36120 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
36130 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73  th the pattern s
36140 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e  tring.  .** Then
36150 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
36160 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72  pattern string r
36170 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c  emains the same,
36180 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  .** the compiled
36190 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
361a0 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
361b0 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
361c0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
361d0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
361e0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
361f0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
36200 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
36210 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
36220 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
36230 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
36240 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
36250 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
36260 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
36270 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
36280 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
36290 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
362a0 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72  nction. ^If ther
362b0 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61  e is no metadata
362c0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
362d0 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ith the function
362e0 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20   argument, this 
362f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
36300 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ata() interface.
36310 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ** returns a NUL
36320 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
36330 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
36340 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
36350 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  X) interface sav
36360 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61  es P as metadata
36370 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
36380 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
36390 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
363a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
363b0 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63  ^Subsequent.** c
363c0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
363d0 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29  get_auxdata(C,N)
363e0 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74   return P from t
363f0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
36400 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
36410 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63  xdata(C,N,P,X) c
36420 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64  all if the metad
36430 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c  ata is still val
36440 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66  id or.** NULL if
36450 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61   the metadata ha
36460 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64  s been discarded
36470 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68  ..** ^After each
36480 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
36490 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
364a0 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73  ,P,X) where X is
364b0 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51   not NULL,.** SQ
364c0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
364d0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
364e0 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20  function X with 
364f0 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63  parameter P exac
36500 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65  tly.** once, whe
36510 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  n the metadata i
36520 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  s discarded..** 
36530 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
36540 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65  o discard the me
36550 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69  tadata at any ti
36560 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c  me, including: <
36570 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e  ul>.** <li> when
36580 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
36590 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
365a0 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f  meter changes, o
365b0 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b  r.** <li> when [
365c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
365d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
365e0 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
365f0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  ed for the.**   
36600 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74     SQL statement
36610 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  , or.** <li> whe
36620 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  n sqlite3_set_au
36630 78 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b  xdata() is invok
36640 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20  ed again on the 
36650 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  same parameter, 
36660 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e  or.** <li> durin
36670 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  g the original s
36680 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
36690 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61  ta() call when a
366a0 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20   memory .**     
366b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
366c0 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29  r occurs. </ul>)
366d0 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65  ^.**.** Note the
366e0 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20   last bullet in 
366f0 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65  particular.  The
36700 20 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e   destructor X in
36710 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74   .** sqlite3_set
36720 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
36730 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
36740 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  d immediately, b
36750 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c  efore the.** sql
36760 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
36770 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65  () interface eve
36780 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63  n returns.  Henc
36790 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
367a0 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c  xdata().** shoul
367b0 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72  d be called near
367c0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
367d0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
367e0 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a  ntation and the.
367f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ** function impl
36800 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
36810 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75  d not make any u
36820 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a  se of P after.**
36830 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
36840 64 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20  data() has been 
36850 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  called..**.** ^(
36860 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
36870 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
36880 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
36890 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
368a0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
368b0 74 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f  ters that are co
368c0 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74  mpile-time const
368d0 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ants, including 
368e0 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
368f0 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72  s and [parameter
36900 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f  s] and expressio
36910 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d  ns composed from
36920 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a   the same.)^.**.
36930 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
36940 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
36950 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
36960 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
36970 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
36980 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
36990 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
369a0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
369b0 4c 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  L sqlite3_get_au
369c0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
369d0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
369e0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
369f0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
36a00 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
36a10 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
36a20 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
36a30 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
36a40 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
36a50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
36a60 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
36a70 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
36a80 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
36a90 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
36aa0 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
36ab0 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
36ac0 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
36ad0 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
36ae0 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
36af0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
36b00 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
36b10 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
36b20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
36b30 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
36b40 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
36b50 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
36b60 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
36b70 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
36b80 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
36b90 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
36ba0 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
36bb0 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
36bc0 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
36bd0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
36be0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
36bf0 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
36c00 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
36c10 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
36c20 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
36c30 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
36c40 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
36c50 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
36c60 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
36c70 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
36c80 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
36c90 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
36ca0 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
36cb0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  s..*/.typedef vo
36cc0 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
36cd0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
36ce0 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
36cf0 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
36d00 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
36d10 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
36d20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
36d30 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
36d40 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
36d50 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
36d60 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
36d70 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
36d80 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
36d90 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
36da0 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54  _context.**.** T
36db0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
36dc0 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
36dd0 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
36de0 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
36df0 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
36e00 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
36e10 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
36e20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36e30 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
36e40 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36e50 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
36e60 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
36e70 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
36e80 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
36e90 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
36ea0 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
36eb0 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
36ec0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
36ed0 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
36ee0 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
36ef0 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
36f00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36f10 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
36f20 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
36f30 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
36f40 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
36f50 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
36f60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36f70 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
36f80 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
36f90 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
36fa0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
36fb0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36fc0 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
36fd0 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
36fe0 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
36ff0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
37000 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
37010 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
37020 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
37030 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
37040 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
37050 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
37060 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 20 61 6e 64  eroblob(C,N) and
37070 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37080 7a 65 72 6f 62 6c 6f 62 36 34 28 43 2c 4e 29 0a  zeroblob64(C,N).
37090 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  ** interfaces se
370a0 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  t the result of 
370b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
370c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
370d0 20 74 6f 20 62 65 0a 2a 2a 20 61 20 42 4c 4f 42   to be.** a BLOB
370e0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
370f0 7a 65 72 6f 20 62 79 74 65 73 20 61 6e 64 20 4e  zero bytes and N
37100 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2e 0a   bytes in size..
37110 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37120 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
37130 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
37140 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
37150 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
37160 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
37170 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
37180 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
37190 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
371a0 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
371b0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
371c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
371d0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
371e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
371f0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
37200 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
37210 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
37220 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
37230 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51  xception..** ^SQ
37240 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
37250 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
37260 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
37270 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
37280 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
37290 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
372a0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
372b0 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
372c0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
372d0 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72  .  ^SQLite inter
372e0 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a  prets the error.
372f0 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  ** message strin
37300 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
37310 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73  esult_error() as
37320 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a   UTF-8. ^SQLite.
37330 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  ** interprets th
37340 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
37350 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37360 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36  or16() as UTF-16
37370 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
37380 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74  te order.  ^If t
37390 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
373a0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
373b0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
373c0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
373d0 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
373e0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
373f0 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65  ite takes as the
37400 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
37410 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68  e all text up th
37420 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
37430 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
37440 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
37450 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
37460 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37470 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
37480 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
37490 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
374a0 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
374b0 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
374c0 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
374d0 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
374e0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
374f0 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
37500 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73  ssage..** ^The s
37510 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
37520 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
37530 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
37540 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d  ().** routines m
37550 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f  ake a private co
37560 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  py of the error 
37570 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66  message text bef
37580 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75  ore.** they retu
37590 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  rn.  Hence, the 
375a0 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
375b0 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
375c0 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
375d0 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
375e0 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
375f0 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  harm..** ^The sq
37600 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37610 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
37620 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
37630 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
37640 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
37650 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
37660 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
37670 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61  ction.  ^By defa
37680 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
37690 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
376a0 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73  _ERROR.  ^A subs
376b0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
376c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
376d0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
376e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
376f0 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20  16() resets the 
37700 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51  error code to SQ
37710 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a  LITE_ERROR..**.*
37720 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
37730 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
37740 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
37750 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
37760 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f  throw an.** erro
37770 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  r indicating tha
37780 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
37790 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74  OB is too long t
377a0 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
377b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
377c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
377d0 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  em() interface c
377e0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
377f0 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f  throw an.** erro
37800 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  r indicating tha
37810 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  t a memory alloc
37820 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a  ation failed..**
37830 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37840 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e  _result_int() in
37850 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
37860 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
37870 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
37880 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
37890 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33  tion to be the 3
378a0 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
378b0 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
378c0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
378d0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
378e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
378f0 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  int64() interfac
37900 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
37910 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
37920 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
37930 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
37940 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
37950 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
37960 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
37970 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
37980 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
37990 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
379a0 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  l() interface se
379b0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
379c0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
379d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
379e0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
379f0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
37a00 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37a10 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
37a20 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
37a30 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  ,.** sqlite3_res
37a40 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20  ult_text16le(), 
37a50 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
37a60 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e  lt_text16be() in
37a70 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20  terfaces.** set 
37a80 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
37a90 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
37aa0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
37ab0 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
37ac0 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63  text string whic
37ad0 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  h is represented
37ae0 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31   as UTF-8, UTF-1
37af0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
37b00 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  der,.** UTF-16 l
37b10 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72  ittle endian, or
37b20 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69   UTF-16 big endi
37b30 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
37b40 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
37b50 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34 28  3_result_text64(
37b60 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
37b70 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
37b80 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c 69  e of an.** appli
37b90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37ba0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
37bb0 74 65 78 74 20 73 74 72 69 6e 67 20 69 6e 20 61  text string in a
37bc0 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73 70  n encoding.** sp
37bd0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
37be0 69 66 74 68 20 28 61 6e 64 20 6c 61 73 74 29 20  ifth (and last) 
37bf0 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68  parameter, which
37c00 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a 20   must be one.** 
37c10 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
37c20 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  , [SQLITE_UTF16]
37c30 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
37c40 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
37c50 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 4c  TF16LE]..** ^SQL
37c60 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
37c70 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
37c80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
37c90 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
37ca0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
37cb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37cc0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
37cd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
37ce0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
37cf0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37d00 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
37d10 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
37d20 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
37d30 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
37d40 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
37d50 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
37d60 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
37d70 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
37d80 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
37d90 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
37da0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
37db0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
37dc0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
37dd0 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
37de0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
37df0 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
37e00 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
37e10 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
37e20 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
37e30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
37e40 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
37e50 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74  on result.  If t
37e60 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
37e70 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
37e80 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73  , then it.** mus
37e90 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
37ea0 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74  fset into the st
37eb0 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e  ring where the N
37ec0 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
37ed0 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66  uld.** appear if
37ee0 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
37ef0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64  e NUL terminated
37f00 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
37f10 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a  aracters occur.*
37f20 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  * in the string 
37f30 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74  at a byte offset
37f40 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68   that is less th
37f50 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  an the value of 
37f60 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d  the 3rd.** param
37f70 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  eter, then the r
37f80 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
37f90 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62  will contain emb
37fa0 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74  edded NULs and t
37fb0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20  he.** result of 
37fc0 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72  expressions oper
37fd0 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73  ating on strings
37fe0 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
37ff0 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
38000 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
38010 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
38020 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
38030 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
38040 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
38050 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
38060 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
38070 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
38080 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
38090 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
380a0 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
380b0 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
380c0 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
380d0 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
380e0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
380f0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
38100 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
38110 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
38120 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
38130 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   to.** sqlite3_r
38140 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
38150 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
38160 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
38170 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
38180 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
38190 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
381a0 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
381b0 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
381c0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
381d0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
381e0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72  he parameter nor
381f0 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
38200 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  or on the conten
38210 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73  t.** when it has
38220 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
38230 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
38240 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
38250 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
38260 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
38270 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
38280 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
38290 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
382a0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
382b0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
382c0 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
382d0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
382e0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
382f0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
38300 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
38310 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
38320 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
38330 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
38340 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
38350 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
38360 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
38370 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
38380 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
38390 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
383a0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72   of the.** [unpr
383b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
383c0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
383d0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
383e0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
383f0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
38400 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
38410 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
38420 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
38430 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
38440 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
38450 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
38460 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
38470 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
38480 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
38490 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
384a0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
384b0 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
384c0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
384d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
384e0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
384f0 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
38500 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
38510 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
38520 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
38530 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
38540 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
38550 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
38560 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
38570 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
38580 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
38590 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
385a0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
385b0 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
385c0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
385d0 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
385e0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
385f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
38600 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
38610 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
38620 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
38630 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
38640 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
38650 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
38660 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
38670 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
38680 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
38690 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
386a0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
386b0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
386c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
386d0 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
386e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
386f0 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 63  blob64(sqlite3_c
38700 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f  ontext*,const vo
38710 69 64 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  id*,.           
38720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38730 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 76  sqlite3_uint64,v
38740 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
38750 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
38760 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
38770 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
38780 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
38790 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a