System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 187c5975a7c4db2fcc8e8699f7cbc128eab4fb08:


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 31 32 2e 32 22 0a 23 64       "3.12.2".#d
10b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
10c0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 31 32  SION_NUMBER 3012
10d0: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
10e0: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20  TE_SOURCE_ID    
10f0: 20 20 22 32 30 31 36 2d 30 34 2d 31 38 20 31 37    "2016-04-18 17
1100: 3a 33 30 3a 33 31 20 39 32 64 63 35 39 66 64 35  :30:31 92dc59fd5
1110: 61 64 36 36 66 36 34 36 36 36 36 30 34 32 65 62  ad66f646666042eb
1120: 30 34 31 39 35 65 33 61 36 31 61 39 65 38 65 22  04195e3a61a9e8e"
1130: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1140: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
1150: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
1160: 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
1170: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c  sqlite3_version,
1180: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
1190: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
11a0: 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65  terfaces provide
11b0: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
11c0: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51  ation as the [SQ
11d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a  LITE_VERSION],.*
11e0: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
11f0: 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b  N_NUMBER], and [
1200: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1210: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1220: 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61   macros.** but a
1230: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  re associated wi
1240: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
1250: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
1260: 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61  ader file.  ^(Ca
1270: 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61  utious.** progra
1280: 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c  mmers might incl
1290: 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61  ude assert() sta
12a0: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72  tements in their
12b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
12c0: 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76  ** verify that v
12d0: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
12e0: 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  y these interfac
12f0: 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63  es match the mac
1300: 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65  ros in.** the he
1310: 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65  ader, and thus e
1320: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
1330: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a  pplication is.**
1340: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1350: 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20  atching library 
1360: 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73  and header files
1370: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  ..**.** <blockqu
1380: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73  ote><pre>.** ass
1390: 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62  ert( sqlite3_lib
13a0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
13b0: 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ==SQLITE_VERSION
13c0: 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73  _NUMBER );.** as
13d0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
13e0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c  ite3_sourceid(),
13f0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1400: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1410: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1420: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1430: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1440: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1450: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1460: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1470: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1480: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
1490: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
14a0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
14b0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
14c0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14d0: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
14e0: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
14f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1500: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1510: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1520: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1530: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1540: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1550: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
1560: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
1570: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
1580: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
1590: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
15a0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
15b0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
15c0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
15d0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
15e0: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
15f0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1600: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1610: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1620: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  BER].  ^The sqli
1630: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66  te3_sourceid() f
1640: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1650: 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
1660: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61   a string consta
1670: 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69  nt whose value i
1680: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68  s the same as th
1690: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  e .** [SQLITE_SO
16a0: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
16b0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a  ocessor macro..*
16c0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
16d0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
16e0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
16f0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
1700: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1710: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
1720: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
1730: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49  on[];.SQLITE_API
1740: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1750: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1760: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76  te3_libversion(v
1770: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
1780: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1790: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
17a0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69  te3_sourceid(voi
17b0: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
17c0: 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
17d0: 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  L sqlite3_libver
17e0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
17f0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1800: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
1810: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
1820: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1830: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1840: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1850: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1860: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
1870: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
1880: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
1890: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
18a0: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
18b0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
18c0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
18d0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
18e0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
18f0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
1900: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
1910: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
1920: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1930: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1940: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1950: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1960: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
1970: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
1980: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
1990: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
19a0: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
19b0: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
19c0: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
19d0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
19e0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
19f0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
1a00: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1a10: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
1a20: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1a30: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1a40: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1a50: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1a60: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1a70: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1a80: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
1a90: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
1aa0: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
1ab0: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
1ac0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1ad0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
1ae0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1af0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
1b00: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
1b10: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
1b20: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1b30: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1b40: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1b50: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1b60: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1b70: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1b80: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1b90: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1ba0: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1bb0: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1bc0: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1bd0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1be0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1bf0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1c00: 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49  DIAGS.SQLITE_API
1c10: 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1c20: 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ALL sqlite3_comp
1c30: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63  ileoption_used(c
1c40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e  onst char *zOptN
1c50: 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ame);.SQLITE_API
1c60: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1c70: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1c80: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1c90: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1ca0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1cb0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1cc0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1cd0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1ce0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1cf0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1d00: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1d10: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1d20: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1d30: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1d40: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1d50: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1d60: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1d70: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1d80: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1d90: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1da0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1db0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1dc0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1dd0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1de0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1df0: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1e00: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1e10: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1e20: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1e30: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1e40: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1e50: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e60: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1e70: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1e80: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1e90: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1ea0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1eb0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1ec0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1ed0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1ee0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1ef0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1f00: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1f10: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1f20: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1f30: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1f40: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1f50: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1f60: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1f70: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1f80: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1f90: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1fa0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1fb0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1fc0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1fd0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
1fe0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
1ff0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2000: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
2010: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
2020: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
2030: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
2040: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
2050: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
2060: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
2070: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
2080: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
2090: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
20a0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
20b0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
20c0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
20d0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
20e0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
20f0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2100: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2110: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2120: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2130: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2140: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2150: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2160: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
2170: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
2180: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
2190: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
21a0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
21b0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
21c0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
21d0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
21e0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
21f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2200: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2210: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2220: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
2230: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
2240: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
2250: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2260: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2270: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2280: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2290: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
22a0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
22b0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
22c0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
22d0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
22e0: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
22f0: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2300: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
2310: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2320: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
2330: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
2340: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2350: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
2360: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2370: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2380: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2390: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23a0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
23b0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
23c0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
23d0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
23e0: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
23f0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
2400: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
2410: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2420: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
2430: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
2440: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
2450: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
2460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
2470: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
2480: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
2490: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
24a0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
24b0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
24c0: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
24d0: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
24e0: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
24f0: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
2500: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2510: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
2520: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
2530: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
2540: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
2550: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
2560: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
2570: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2580: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20  close_v2()] are 
2590: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e  its destructors.
25a0: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
25b0: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
25c0: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
25d0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25e0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
25f0: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2600: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
2610: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
2620: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
2630: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
2640: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
2650: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
2660: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
2670: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
2680: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
2690: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
26a0: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b  teger Types.** K
26b0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
26c0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
26d0: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
26e0: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
26f0: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
2700: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
2710: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
2720: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
2730: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
2740: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
2750: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
2760: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
2770: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
2780: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
2790: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
27a0: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
27b0: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
27c0: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
27d0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
27e0: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
27f0: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
2800: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
2810: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
2820: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79   sqlite_int64 ty
2840: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
2850: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  teger values.** 
2860: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
2870: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
2880: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
2890: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e  75807 inclusive.
28a0: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
28b0: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  3_uint64 and sql
28c0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
28d0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
28e0: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65  er values .** be
28f0: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34  tween 0 and +184
2900: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31  4674407370955161
2910: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a  5 inclusive..*/.
2920: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
2930: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
2940: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2950: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
2960: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2970: 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54  igned SQLITE_INT
2980: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
2990: 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66  int64;.#elif def
29a0: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c  ined(_MSC_VER) |
29b0: 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c  | defined(__BORL
29c0: 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65  ANDC__).  typede
29d0: 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  f __int64 sqlite
29e0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
29f0: 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74  f unsigned __int
2a00: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2a10: 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65  ;.#else.  typede
2a20: 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  f long long int 
2a30: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
2a40: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
2a50: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
2a60: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2a70: 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c  ndif.typedef sql
2a80: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
2a90: 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66  3_int64;.typedef
2aa0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73   sqlite_uint64 s
2ab0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a  qlite3_uint64;..
2ac0: 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69  /*.** If compili
2ad0: 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73  ng for a process
2ae0: 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c  or that lacks fl
2af0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70  oating point sup
2b00: 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74  port,.** substit
2b10: 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20  ute integer for 
2b20: 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a  floating-point..
2b30: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
2b40: 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50  _OMIT_FLOATING_P
2b50: 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f  OINT.# define do
2b60: 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  uble sqlite3_int
2b70: 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  64.#endif../*.**
2b80: 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69   CAPI3REF: Closi
2b90: 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  ng A Database Co
2ba0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 54  nnection.** DEST
2bb0: 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a  RUCTOR: sqlite3.
2bc0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2bd0: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73  e3_close() and s
2be0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2bf0: 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  ) routines are d
2c00: 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f  estructors.** fo
2c10: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  r the [sqlite3] 
2c20: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c  object..** ^Call
2c30: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f  s to sqlite3_clo
2c40: 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  se() and sqlite3
2c50: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75  _close_v2() retu
2c60: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  rn [SQLITE_OK] i
2c70: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  f.** the [sqlite
2c80: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63  3] object is suc
2c90: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f  cessfully destro
2ca0: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f  yed and all asso
2cb0: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72  ciated.** resour
2cc0: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
2cd0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ted..**.** ^If t
2ce0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2cf0: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69  ection is associ
2d00: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61  ated with unfina
2d10: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a  lized prepared.*
2d20: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20  * statements or 
2d30: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
2d40: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74  e3_backup object
2d50: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  s then sqlite3_c
2d60: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c  lose().** will l
2d70: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73  eave the databas
2d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
2d90: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  n and return [SQ
2da0: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e  LITE_BUSY]..** ^
2db0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  If sqlite3_close
2dc0: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
2dd0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2de0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2df0: 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75  ents.** and/or u
2e00: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
2e10: 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20  3_backups, then 
2e20: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2e30: 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a  nection becomes.
2e40: 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22  ** an unusable "
2e50: 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69  zombie" which wi
2e60: 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
2e70: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
2e80: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74  when the.** last
2e90: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ea0: 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2eb0: 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c   or the last sql
2ec0: 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a  ite3_backup is.*
2ed0: 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65  * finished.  The
2ee0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2ef0: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
2f00: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
2f10: 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c  e with.** host l
2f20: 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72  anguages that ar
2f30: 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63  e garbage collec
2f40: 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74  ted, and where t
2f50: 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63  he order in whic
2f60: 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73  h.** destructors
2f70: 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61   are called is a
2f80: 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  rbitrary..**.** 
2f90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
2fa0: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  uld [sqlite3_fin
2fb0: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2fc0: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20  ] all [prepared 
2fd0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20  statements],.** 
2fe0: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
2ff0: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c  ose | close] all
3000: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
3010: 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
3020: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20  3_backup_finish 
3030: 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73  | finish] all [s
3040: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3050: 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65  bjects associate
3060: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73  d.** with the [s
3070: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
3080: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69  rior to attempti
3090: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
30a0: 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20  object.  ^If.** 
30b0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
30c0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  () is called on 
30d0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
30e0: 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69  ection] that sti
30f0: 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61  ll has.** outsta
3100: 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20  nding [prepared 
3110: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c  statements], [BL
3120: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3130: 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  /or.** [sqlite3_
3140: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3150: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20  then it returns 
3160: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20  [SQLITE_OK] and 
3170: 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e  the deallocation
3180: 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73  .** of resources
3190: 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e 74   is deferred unt
31a0: 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64  il all [prepared
31b0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42   statements], [B
31c0: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a  LOB handles],.**
31d0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61   and [sqlite3_ba
31e0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72  ckup] objects ar
31f0: 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64  e also destroyed
3200: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b  ..**.** ^If an [
3210: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
3220: 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68 69  is destroyed whi
3230: 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  le a transaction
3240: 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65   is open,.** the
3250: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3260: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
3270: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
3280: 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72   The C parameter
3290: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
32a0: 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69  se(C)] and [sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d  te3_close_v2(C)]
32c0: 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
32d0: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
32e0: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
32f0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
3300: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
3310: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
3320: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
3330: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
3340: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
3350: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
3360: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
3370: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
3380: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20  ite3_close() or 
3390: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
33a0: 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  () with a NULL p
33b0: 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65  ointer.** argume
33c0: 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  nt is a harmless
33d0: 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54   no-op..*/.SQLIT
33e0: 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
33f0: 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
3400: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29  _close(sqlite3*)
3410: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
3420: 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3440: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3450: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3460: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
3470: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
3480: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
3490: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
34a0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
34b0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
34c0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
34d0: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
34e0: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
34f0: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
3500: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
3510: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
3520: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
3530: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
3540: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3550: 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
3560: 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
3570: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3580: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
3590: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
35a0: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
35b0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
35c0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
35d0: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
35e0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20  finalize()],.** 
35f0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
3600: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75  pplication to ru
3610: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65  n multiple state
3620: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20  ments of SQL.** 
3630: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
3640: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43  o use a lot of C
3650: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54   code. .**.** ^T
3660: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3670: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73  ) interface runs
3680: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54   zero or more UT
3690: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20  F-8 encoded,.** 
36a0: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
36b0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
36c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74  s passed into it
36d0: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a  s 2nd argument,.
36e0: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ** in the contex
36f0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
3700: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
3710: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20  assed in as its 
3720: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  1st.** argument.
3730: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
3740: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74  ck function of t
3750: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3760: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
3770: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
3780: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76  , then it is inv
3790: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65  oked for each re
37a0: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69  sult row.** comi
37b0: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76  ng out of the ev
37c0: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74  aluated SQL stat
37d0: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74  ements.  ^The 4t
37e0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  h argument to.**
37f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3800: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75  is relayed throu
3810: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72  gh to the 1st ar
3820: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a  gument of each.*
3830: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63  * callback invoc
3840: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20  ation.  ^If the 
3850: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72  callback pointer
3860: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3870: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  ().** is NULL, t
3880: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20  hen no callback 
3890: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20  is ever invoked 
38a0: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20  and result rows 
38b0: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a  are.** ignored..
38c0: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  **.** ^If an err
38d0: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
38e0: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53  evaluating the S
38f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
3900: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  ssed into.** sql
3910: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65  ite3_exec(), the
3920: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  n execution of t
3930: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
3940: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a  ment stops and.*
3950: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61  * subsequent sta
3960: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70  tements are skip
3970: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74  ped.  ^If the 5t
3980: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3990: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
39a0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
39b0: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  n any error mess
39c0: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
39d0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
39e0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
39f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
3a00: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  nd passed back t
3a10: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3a20: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20  arameter..** To 
3a30: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61  avoid memory lea
3a40: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ks, the applicat
3a50: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b  ion should invok
3a60: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
3a70: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d  )].** on error m
3a80: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72  essage strings r
3a90: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
3aa0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3ab0: 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r of.** sqlite3_
3ac0: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
3ad0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3ae0: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3af0: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3b00: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3b10: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3b20: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3b30: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3b40: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3b60: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
3b70: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
3b80: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
3b90: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
3ba0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
3bb0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3bc0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
3bd0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3be0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3bf0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3c00: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3c10: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3c20: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
3c30: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
3c40: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
3c50: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3c60: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
3c70: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
3c80: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3c90: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3ca0: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3cb0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3cc0: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3cd0: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3ce0: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3cf0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3d00: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3d10: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3d20: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
3d30: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
3d40: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3d50: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
3d60: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
3d70: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
3d80: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3d90: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3da0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3db0: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3dc0: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3dd0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3de0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3df0: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3e00: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3e10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3e20: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3e30: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3e40: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
3e50: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
3e60: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
3e70: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
3e80: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3e90: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3ea0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3eb0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3ec0: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3ed0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3ee0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3ef0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3f00: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3f10: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3f20: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
3f30: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
3f40: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
3f50: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
3f60: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
3f70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
3f80: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3f90: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3fa0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3fb0: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3fc0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3fd0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3fe0: 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72  ation must ensur
3ff0: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
4000: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4010: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
4020: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
4030: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
4040: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
4050: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
4060: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
4070: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
4080: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
4090: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
40a0: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
40b0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
40c0: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
40d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
40e0: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <li>
40f0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
4100: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
4110: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
4120: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
4130: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
4140: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
4150: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4160: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
4170: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
4180: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c  .** </ul>.*/.SQL
4190: 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
41a0: 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
41b0: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
41c0: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
41f0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
4200: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
4210: 20 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 2f 2a 20 53 51 4c            /* SQL
4230: 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
4240: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
4250: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
4260: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
4270: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
4280: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
4290: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
42c0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
42d0: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
42e0: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4300: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
4310: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
4320: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
4330: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  F: Result Codes.
4340: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65  ** KEYWORDS: {re
4350: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4360: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  tions}.**.** Man
4370: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
4380: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
4390: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
43a0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
43b0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
43c0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
43d0: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
43e0: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
43f0: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4400: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4410: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4420: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4430: 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20  also: [extended 
4440: 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69  result code defi
4450: 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66  nitions].*/.#def
4460: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
4470: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
4480: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
4490: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
44a0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
44b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
44c0: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
44d0: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
44e0: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
44f0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4500: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
4510: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
4520: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
4530: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
4540: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
4550: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
4560: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
4570: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4580: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
4590: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
45a0: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
45b0: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
45c0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
45d0: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
45e0: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
45f0: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
4600: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4610: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
4620: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
4630: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
4640: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
4650: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4660: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
4670: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
4680: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
4690: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
46a0: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
46b0: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
46c0: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
46d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46e0: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
46f0: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
4700: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
4710: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
4720: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4730: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
4740: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
4750: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
4760: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
4770: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
4780: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
4790: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
47a0: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
47b0: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
47c0: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
47d0: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
47e0: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
47f0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
4800: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
4810: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
4820: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
4830: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
4840: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
4850: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
4860: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
4870: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
4880: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
4890: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
48a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
48b0: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
48c0: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
48d0: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
48e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
48f0: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
4900: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
4910: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
4920: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
4930: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
4940: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
4950: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
4960: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
4970: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
4980: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
4990: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
49a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
49b0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
49c0: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
49d0: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
49e0: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
49f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
4a00: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
4a10: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
4a20: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
4a30: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
4a40: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
4a50: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
4a60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a70: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
4a80: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
4a90: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
4aa0: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
4ab0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ac0: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
4ad0: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
4ae0: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4af0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
4b00: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
4b10: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
4b20: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
4b30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b40: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
4b50: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
4b60: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
4b70: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
4b80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b90: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
4ba0: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
4bb0: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
4bc0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
4bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4be0: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20  NOTICE      27  
4bf0: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e   /* Notification
4c00: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4c10: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4c20: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20  SQLITE_WARNING  
4c30: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69     28   /* Warni
4c40: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ngs from sqlite3
4c50: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
4c60: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4c70: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4c80: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4c90: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4ca0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4cb0: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4cc0: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4cd0: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4ce0: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4cf0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4d00: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4d10: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4d20: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4d30: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4d40: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4d50: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d  ode definitions}
4d60: 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65  .**.** In its de
4d70: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
4d80: 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20  ion, SQLite API 
4d90: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
4da0: 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65  one of 30 intege
4db0: 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64  r.** [result cod
4dc0: 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65  es].  However, e
4dd0: 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68  xperience has sh
4de0: 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66  own that many of
4df0: 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74  .** these result
4e00: 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63   codes are too c
4e10: 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20  oarse-grained.  
4e20: 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76  They do not prov
4e30: 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69  ide as.** much i
4e40: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
4e50: 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f   problems as pro
4e60: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c  grammers might l
4e70: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f  ike.  In an effo
4e80: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73  rt to.** address
4e90: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72   this, newer ver
4ea0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
4eb0: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61  (version 3.3.8 a
4ec0: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
4ed0: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
4ee0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
4ef0: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
4f00: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
4f10: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
4f20: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
4f30: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64   These [extended
4f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
4f50: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4f60: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4f70: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4f80: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4f90: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4fa0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4fb0: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4fc0: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64    Or, the extend
4fd0: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74  ed code for.** t
4fe0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
4ff0: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61  rror can be obta
5000: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
5010: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
5020: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23  errcode()]..*/.#
5030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5040: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
5050: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5060: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
5070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5080: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
5090: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50a0: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
50b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
50c0: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
50d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
50e0: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
50f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5100: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  _FSYNC          
5110: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5120: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5140: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  DIR_FSYNC       
5150: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5160: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5170: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
5180: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20  RUNCATE         
5190: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51a0: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
51b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
51c0: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20  TAT             
51d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
51e0: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
51f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
5200: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
5210: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5220: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5230: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
5240: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5250: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
5260: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5270: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
5280: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  E            (SQ
5290: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
52a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
52c0: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ED           (SQ
52d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
52e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d  LITE_IOERR_NOMEM
5300: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5310: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32  LITE_IOERR | (12
5320: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5330: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53  LITE_IOERR_ACCES
5340: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  S            (SQ
5350: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33  LITE_IOERR | (13
5360: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5370: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b  LITE_IOERR_CHECK
5380: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51  RESERVEDLOCK (SQ
5390: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34  LITE_IOERR | (14
53a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
53b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20  LITE_IOERR_LOCK 
53c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
53d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35  LITE_IOERR | (15
53e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
53f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45  LITE_IOERR_CLOSE
5400: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5410: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36  LITE_IOERR | (16
5420: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5430: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43  LITE_IOERR_DIR_C
5440: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51  LOSE         (SQ
5450: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37  LITE_IOERR | (17
5460: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5470: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50  LITE_IOERR_SHMOP
5480: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51  EN           (SQ
5490: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38  LITE_IOERR | (18
54a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49  LITE_IOERR_SHMSI
54c0: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ZE           (SQ
54d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39  LITE_IOERR | (19
54e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f  LITE_IOERR_SHMLO
5500: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51  CK           (SQ
5510: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30  LITE_IOERR | (20
5520: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5530: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41  LITE_IOERR_SHMMA
5540: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  P            (SQ
5550: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31  LITE_IOERR | (21
5560: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5570: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20  LITE_IOERR_SEEK 
5580: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5590: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32  LITE_IOERR | (22
55a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
55b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
55c0: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51  E_NOENT      (SQ
55d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33  LITE_IOERR | (23
55e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
55f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20  LITE_IOERR_MMAP 
5600: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5610: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34  LITE_IOERR | (24
5620: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5630: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45  LITE_IOERR_GETTE
5640: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51  MPPATH       (SQ
5650: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35  LITE_IOERR | (25
5660: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5670: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50  LITE_IOERR_CONVP
5680: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51  ATH          (SQ
5690: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36  LITE_IOERR | (26
56a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
56b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45  LITE_IOERR_VNODE
56c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
56d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37  LITE_IOERR | (27
56e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
56f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20  LITE_IOERR_AUTH 
5700: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5710: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38  LITE_IOERR | (28
5720: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5730: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52  LITE_LOCKED_SHAR
5740: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51  EDCACHE      (SQ
5750: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28  LITE_LOCKED |  (
5760: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5770: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56  QLITE_BUSY_RECOV
5780: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53  ERY           (S
5790: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
57a0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
57b0: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50  SQLITE_BUSY_SNAP
57c0: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28  SHOT           (
57d0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
57e0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
57f0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5800: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20  _NOTEMPDIR      
5810: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5820: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5830: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5840: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20  EN_ISDIR        
5850: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5860: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  EN | (2<<8)).#de
5870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5880: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20  OPEN_FULLPATH   
5890: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
58a0: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OPEN | (3<<8)).#
58b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
58c0: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20  NTOPEN_CONVPATH 
58d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
58e0: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29  NTOPEN | (4<<8))
58f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5900: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5910: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5920: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
5930: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5940: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
5950: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
5960: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
5970: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5980: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
5990: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
59a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
59b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
59c0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
59d0: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
59e0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
59f0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5a00: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5a10: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28  DBMOVED        (
5a20: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5a30: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5a40: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
5a50: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
5a60: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
5a70: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5a80: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5a90: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
5aa0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5ab0: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
5ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5ad0: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
5ae0: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
5af0: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
5b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b10: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
5b20: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
5b30: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
5b40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5b60: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
5b70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5b80: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5b90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ba0: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
5bb0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5bc0: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
5bd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5be0: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
5bf0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5c00: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
5c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c20: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
5c30: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
5c40: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
5c50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5c60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
5c70: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
5c80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5c90: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5ca0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5cb0: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
5cc0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5cd0: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
5ce0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5cf0: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20  TRAINT_ROWID    
5d00: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5d10: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29  TRAINT |(10<<8))
5d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d30: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57  NOTICE_RECOVER_W
5d40: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  AL      (SQLITE_
5d50: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29  NOTICE | (1<<8))
5d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d70: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52  NOTICE_RECOVER_R
5d80: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f  OLLBACK (SQLITE_
5d90: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29  NOTICE | (2<<8))
5da0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5db0: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45  WARNING_AUTOINDE
5dc0: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  X       (SQLITE_
5dd0: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29  WARNING | (1<<8)
5de0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5df0: 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20  _AUTH_USER      
5e00: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5e10: 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a  _AUTH | (1<<8)).
5e20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5e30: 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20   Flags For File 
5e40: 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a  Open Operations.
5e50: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20  **.** These bit 
5e60: 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e  values are inten
5e70: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74  ded for use in t
5e80: 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65  he.** 3rd parame
5e90: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
5ea0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
5eb0: 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20  nterface and.** 
5ec0: 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  in the 4th param
5ed0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
5ee0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
5ef0: 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69  method..*/.#defi
5f00: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5f10: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
5f20: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
5f30: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5f40: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5f50: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5f60: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
5f70: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
5f80: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5f90: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5fa0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
5fb0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
5fc0: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
5fd0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5fe0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5ff0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
6000: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
6010: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
6020: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6030: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
6040: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
6050: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
6060: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6070: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
6080: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
6090: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
60a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
60b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  ne SQLITE_OPEN_U
60c0: 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RI              
60d0: 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f  0x00000040  /* O
60e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
60f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6100: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6110: 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20 20  EMORY           
6120: 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f  0x00000080  /* O
6130: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6140: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6150: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6160: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
6170: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
6180: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6190: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
61a0: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
61b0: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
61c0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
61d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
61e0: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
61f0: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
6200: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6210: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6220: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
6230: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
6240: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6250: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
6260: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
6270: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
6280: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6290: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
62a0: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
62b0: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
62c0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
62d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
62e0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
62f0: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
6300: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6310: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
6320: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
6330: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
6340: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6350: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6360: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
6370: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
6380: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
6390: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
63a0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
63b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
63c0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
63d0: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
63e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
63f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
6410: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
6420: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
6430: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6440: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6450: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57  ne SQLITE_OPEN_W
6460: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AL              
6470: 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56  0x00080000  /* V
6480: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52  FS only */../* R
6490: 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20  eserved:        
64a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
64b0: 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a   0x00F00000 */..
64c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
64d0: 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72  Device Character
64e0: 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65  istics.**.** The
64f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
6500: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f  ristics method o
6510: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
6520: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62  o_methods].** ob
6530: 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ject returns an 
6540: 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
6550: 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65   a vector of the
6560: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73  se.** bit values
6570: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20   expressing I/O 
6580: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  characteristics 
6590: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72  of the mass stor
65a0: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  age.** device th
65b0: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c  at holds the fil
65c0: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  e that the [sqli
65d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
65e0: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a  ** refers to..**
65f0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
6600: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
6610: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
6620: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
6630: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
6640: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
6650: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
6660: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
6670: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
6680: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
6690: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
66a0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
66b0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
66c0: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
66d0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
66e0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
66f0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
6700: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
6710: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
6720: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
6730: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
6740: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
6750: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
6760: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
6770: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
6780: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
6790: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
67a0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
67b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
67c0: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
67d0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
67e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
67f0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
6800: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
6810: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
6820: 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20   xWrite().  The 
6830: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
6840: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
6850: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6860: 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65  that.** after re
6870: 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  boot following a
6880: 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20   crash or power 
6890: 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62  loss, the only b
68a0: 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c  ytes in a.** fil
68b0: 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74  e that were writ
68c0: 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69  ten at the appli
68d0: 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67  cation level mig
68e0: 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a  ht have changed.
68f0: 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61  ** and that adja
6900: 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e  cent bytes, even
6910: 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68   bytes within th
6920: 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72  e same sector ar
6930: 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20  e.** guaranteed 
6940: 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e  to be unchanged.
6950: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6960: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
6970: 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67  HEN_OPEN.** flag
6980: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 61   indicate that a
6990: 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
69a0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 65  deleted when ope
69b0: 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54  n.  The.** SQLIT
69c0: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
69d0: 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73  E flag indicates
69e0: 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 20 69   that the file i
69f0: 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c  s on.** read-onl
6a00: 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e 6e  y media and cann
6a10: 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 65 76  ot be changed ev
6a20: 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73 20  en by processes 
6a30: 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64  with.** elevated
6a40: 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a   privileges..*/.
6a50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6a60: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
6a70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6a80: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
6a90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6aa0: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
6ab0: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
6ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6ad0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
6ae0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6af0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
6b00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6b10: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6b20: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
6b30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6b40: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
6b50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6b60: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
6b70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
6b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6b90: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
6ba0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6bb0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
6bc0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
6bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6be0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
6bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6c00: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
6c10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6c20: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
6c30: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
6c40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6c50: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6c60: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6c70: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
6c80: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6c90: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
6ca0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
6cb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6cc0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
6cd0: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
6ce0: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
6cf0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6d00: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
6d10: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
6d20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6d30: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20  IMMUTABLE       
6d40: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
6d50: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
6d60: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20  F: File Locking 
6d70: 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  Levels.**.** SQL
6d80: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
6d90: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6da0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6db0: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
6dc0: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
6dd0: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
6de0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
6df0: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
6e00: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6e10: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
6e20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6e30: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
6e40: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
6e50: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
6e60: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
6e70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6e80: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
6e90: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
6ea0: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
6eb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6ec0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
6ed0: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
6ee0: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
6ef0: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a  ion Type Flags.*
6f00: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65  *.** When SQLite
6f10: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79   invokes the xSy
6f20: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61  nc() method of a
6f30: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
6f40: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6f50: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69   it uses a combi
6f60: 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  nation of.** the
6f70: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
6f80: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  s as the second 
6f90: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
6fa0: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  When the SQLITE_
6fb0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c  SYNC_DATAONLY fl
6fc0: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d  ag is used, it m
6fd0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  eans that the.**
6fe0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20   sync operation 
6ff0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c  only needs to fl
7000: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73  ush data to mass
7010: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65   storage.  Inode
7020: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
7030: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73  need not be flus
7040: 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65  hed. If the lowe
7050: 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74  r four bits of t
7060: 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c  he flag.** equal
7070: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7080: 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  MAL, that means 
7090: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73  to use normal fs
70a0: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e  ync() semantics.
70b0: 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72  .** If the lower
70c0: 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c   four bits equal
70d0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
70e0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  L, that means.**
70f0: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58   to use Mac OS X
7100: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
7110: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
7120: 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74  ()..**.** Do not
7130: 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c   confuse the SQL
7140: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7150: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7160: 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69  FULL flags.** wi
7170: 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73  th the [PRAGMA s
7180: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d  ynchronous]=NORM
7190: 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73  AL and [PRAGMA s
71a0: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c  ynchronous]=FULL
71b0: 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54  .** settings.  T
71c0: 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20  he [synchronous 
71d0: 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e  pragma] determin
71e0: 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f  es when calls to
71f0: 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46   the.** xSync VF
7200: 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61  S method occur a
7210: 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f  nd applies unifo
7220: 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  rmly across all 
7230: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68  platforms..** Th
7240: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7250: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7260: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20  SYNC_FULL flags 
7270: 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a  determine how.**
7280: 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69   energetic or ri
7290: 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66  gorous or forcef
72a0: 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72  ul the sync oper
72b0: 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a  ations are and.*
72c0: 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69  * only make a di
72d0: 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20  fference on Mac 
72e0: 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61  OSX for the defa
72f0: 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e  ult SQLite code.
7300: 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79  .** (Third-party
7310: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7320: 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  ions might also 
7330: 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
7340: 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
7350: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7360: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
7370: 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f  NC_FULL, but amo
7380: 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74  ng the.** operat
7390: 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69  ing systems nati
73a0: 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62  vely supported b
73b0: 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d  y SQLite, only M
73c0: 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20  ac OSX.** cares 
73d0: 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72  about the differ
73e0: 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e  ence.).*/.#defin
73f0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7400: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30  RMAL        0x00
7410: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
7420: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20  TE_SYNC_FULL    
7430: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64        0x00003.#d
7440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7450: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20  C_DATAONLY      
7460: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43  0x00010../*.** C
7470: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7480: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20  rface Open File 
7490: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20  Handle.**.** An 
74a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
74b0: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
74c0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e   an open file in
74d0: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
74e0: 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72  3_vfs | OS inter
74f0: 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e  face layer].  In
7500: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
7510: 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  rface.** impleme
7520: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a  ntations will.**
7530: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73   want to subclas
7540: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79  s this object by
7550: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74   appending addit
7560: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20  ional fields.** 
7570: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73  for their own us
7580: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73  e.  The pMethods
7590: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e   entry is a poin
75a0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
75b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
75c0: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
75d0: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f  fines methods fo
75e0: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20  r performing.** 
75f0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f  I/O operations o
7600: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  n the open file.
7610: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
7620: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
7630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74  sqlite3_file;.st
7640: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
7650: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75  e {.  const stru
7660: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
7670: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b  thods *pMethods;
7680: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
7690: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f   an open file */
76a0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
76b0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
76c0: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d  e File Virtual M
76d0: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a  ethods Object.**
76e0: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
76f0: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
7700: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7710: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65   method populate
7720: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s an.** [sqlite3
7730: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f  _file] object (o
7740: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79  r, more commonly
7750: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  , a subclass of 
7760: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
7770: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69  file] object) wi
7780: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  th a pointer to 
7790: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
77a0: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54  his object..** T
77b0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
77c0: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75  es the methods u
77d0: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  sed to perform v
77e0: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e  arious operation
77f0: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65  s.** against the
7800: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65   open file repre
7810: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73  sented by the [s
7820: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7830: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ect..**.** If th
7840: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7850: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74  Open] method set
7860: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  s the sqlite3_fi
7870: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
7880: 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e  ent .** to a non
7890: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
78a0: 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
78b0: 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73  io_methods.xClos
78c0: 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20  e method.** may 
78d0: 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20  be invoked even 
78e0: 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  if the [sqlite3_
78f0: 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72  vfs.xOpen] repor
7900: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c  ted that it fail
7910: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79  ed.  The.** only
7920: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20   way to prevent 
7930: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65  a call to xClose
7940: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
7950: 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  led [sqlite3_vfs
7960: 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f  .xOpen].** is fo
7970: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  r the [sqlite3_v
7980: 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74  fs.xOpen] to set
7990: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
79a0: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
79b0: 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  nt.** to NULL..*
79c0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
79d0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
79e0: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
79f0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7a00: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
7a10: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
7a20: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
7a30: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
7a40: 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ync()..** The se
7a50: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
7a60: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
7a70: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b  fullsync.  The [
7a80: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7a90: 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61  ONLY].** flag ma
7aa0: 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20  y be ORed in to 
7ab0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e  indicate that on
7ac0: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74  ly the data of t
7ad0: 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e  he file.** and n
7ae0: 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65  ot its inode nee
7af0: 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e  ds to be synced.
7b00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67  .**.** The integ
7b10: 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f  er values to xLo
7b20: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
7b30: 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a  () are one of.**
7b40: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7b50: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
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 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
7b80: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7b90: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a  LOCK_RESERVED],.
7ba0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7bb0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
7bc0: 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
7bd0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7be0: 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78  ]..** </ul>.** x
7bf0: 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73  Lock() increases
7c00: 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f   the lock. xUnlo
7c10: 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74  ck() decreases t
7c20: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20  he lock..** The 
7c30: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
7c40: 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63  ck() method chec
7c50: 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64  ks whether any d
7c60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
7c70: 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e  on,.** either in
7c80: 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72   this process or
7c90: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70   in some other p
7ca0: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69  rocess, is holdi
7cb0: 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a  ng a RESERVED,.*
7cc0: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58  * PENDING, or EX
7cd0: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20  CLUSIVE lock on 
7ce0: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65  the file.  It re
7cf0: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66  turns true.** if
7d00: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69   such a lock exi
7d10: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74  sts and false ot
7d20: 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54  herwise..**.** T
7d30: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
7d40: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
7d50: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
7d60: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
7d70: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
7d80: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
7d90: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
7da0: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
7db0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
7dc0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
7dd0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
7de0: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
7df0: 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69  ument is an.** i
7e00: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
7e10: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
7e20: 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  nt is a generic 
7e30: 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64  pointer intended
7e40: 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20   to.** point to 
7e50: 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  a structure that
7e60: 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67   may contain arg
7e70: 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20  uments or space 
7e80: 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77  in which to.** w
7e90: 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75  rite return valu
7ea0: 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75  es.  Potential u
7eb0: 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e  ses for xFileCon
7ec0: 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a  trol() might be.
7ed0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20  ** functions to 
7ee0: 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20  enable blocking 
7ef0: 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f  locks with timeo
7f00: 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74  uts, to change t
7f10: 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74  he.** locking st
7f20: 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d  rategy (for exam
7f30: 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66  ple to use dot-f
7f40: 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69  ile locks), to i
7f50: 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20  nquire.** about 
7f60: 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20  the status of a 
7f70: 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61  lock, or to brea
7f80: 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20  k stale locks.  
7f90: 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f  The SQLite.** co
7fa0: 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20  re reserves all 
7fb0: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
7fc0: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
7fd0: 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c  n use..** A [fil
7fe0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
7ff0: 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  s | list of opco
8000: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
8010: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
8020: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
8030: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
8040: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
8050: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
8060: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
8070: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
8080: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
8090: 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d  cts.  VFS implem
80a0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
80b0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
80c0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72  TE_NOTFOUND] for
80d0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70   file control op
80e0: 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20  codes that they 
80f0: 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e  do not.** recogn
8100: 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ize..**.** The x
8110: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
8120: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
8130: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
8140: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
8150: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
8160: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
8170: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
8180: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
8190: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
81a0: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
81b0: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
81c0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
81d0: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
81e0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
81f0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
8200: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
8210: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
8220: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
8230: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
8240: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
8250: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8260: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
8270: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8280: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
8290: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
82a0: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
82b0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
82c0: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
82d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
82e0: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
82f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8300: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
8310: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8320: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
8330: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8340: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
8350: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8360: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
8370: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8380: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
8390: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
83a0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
83b0: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
83c0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
83d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
83e0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
83f0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
8400: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
8410: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
8420: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
8430: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
8440: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
8450: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
8460: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
8470: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
8480: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
8490: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
84a0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
84b0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
84c0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
84d0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
84e0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
84f0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
8500: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
8510: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
8520: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
8530: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
8540: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
8550: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
8560: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
8570: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
8580: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8590: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
85a0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
85b0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
85c0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
85d0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
85e0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
85f0: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
8600: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
8610: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
8620: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
8630: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
8640: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
8650: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
8660: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
8670: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
8680: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
8690: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
86a0: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
86b0: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
86c0: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
86d0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
86e0: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
86f0: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
8700: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
8710: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
8720: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8730: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
8740: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
8750: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
8760: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
8770: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
8780: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
8790: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
87a0: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
87b0: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
87c0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
87d0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
87e0: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
87f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
8800: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8810: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8820: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8830: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
8840: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8850: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
8860: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
8870: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8880: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
8890: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
88a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
88b0: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
88c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
88d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88e0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
88f0: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
8900: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8910: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
8920: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
8930: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
8940: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
8950: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
8960: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8970: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
8980: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
8990: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
89a0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
89b0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
89c0: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
89d0: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
89e0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
89f0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
8a00: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
8a10: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
8a20: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
8a30: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
8a40: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
8a50: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
8a60: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8a70: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
8a80: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
8a90: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
8aa0: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
8ab0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
8ac0: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
8ad0: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
8ae0: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
8af0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8b00: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
8b10: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74   */.  int (*xFet
8b20: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8b30: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8b40: 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74   iOfst, int iAmt
8b50: 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20  , void **pp);.  
8b60: 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28  int (*xUnfetch)(
8b70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8b80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8b90: 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20  st, void *p);.  
8ba0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8bb0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8bc0: 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a  ersion 3 */.  /*
8bd0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
8be0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
8bf0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
8c00: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
8c10: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
8c20: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
8c30: 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57   Opcodes.** KEYW
8c40: 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74  ORDS: {file cont
8c50: 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69  rol opcodes} {fi
8c60: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
8c70: 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  e}.**.** These i
8c80: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
8c90: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72   are opcodes for
8ca0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
8cb0: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  l method.** of t
8cc0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
8cd0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
8ce0: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  nd for the [sqli
8cf0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8d00: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
8d10: 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  ..**.** <ul>.** 
8d20: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8d30: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a  TL_LOCKSTATE]].*
8d40: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8d50: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f  NTL_LOCKSTATE] o
8d60: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
8d70: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
8d80: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
8d90: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
8da0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77  trol method to w
8db0: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74  rite the current
8dc0: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65   state of.** the
8dd0: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53   lock (one of [S
8de0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
8df0: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  , [SQLITE_LOCK_S
8e00: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  HARED],.** [SQLI
8e10: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
8e20: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8e30: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51  PENDING], or [SQ
8e40: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
8e50: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e  IVE]).** into an
8e60: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68   integer that th
8e70: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
8e80: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20  points to. This 
8e90: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
8ea0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
8eb0: 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79  ting and is only
8ec0: 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 20   available when 
8ed0: 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  the SQLITE_TEST.
8ee0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
8ef0: 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
8f00: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8f10: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
8f20: 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NT]].** The [SQL
8f30: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
8f40: 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  INT] opcode is u
8f50: 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f  sed by SQLite to
8f60: 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a   give the VFS.**
8f70: 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66   layer a hint of
8f80: 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64   how large the d
8f90: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
8fa0: 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72  l grow to be dur
8fb0: 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  ing the.** curre
8fc0: 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  nt transaction. 
8fd0: 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f   This hint is no
8fe0: 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  t guaranteed to 
8ff0: 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20  be accurate but 
9000: 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63  it.** is often c
9010: 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72  lose.  The under
9020: 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20  lying VFS might 
9030: 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c  choose to preall
9040: 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a  ocate database.*
9050: 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73  * file space bas
9060: 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ed on this hint 
9070: 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70  in order to help
9080: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64   writes to the d
9090: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
90a0: 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a  run faster..**.*
90b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
90c0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
90d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
90e0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
90f0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
9100: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
9110: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
9120: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
9130: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
9140: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
9150: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
9160: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
9170: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
9180: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
9190: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
91a0: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
91b0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
91c0: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
91d0: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
91e0: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
91f0: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
9200: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
9210: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
9220: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
9230: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
9240: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
9250: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
9260: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
9270: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
9280: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
9290: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
92a0: 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c  systems..**.** <
92b0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
92c0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d  L_FILE_POINTER]]
92d0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
92e0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
92f0: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ER] opcode is us
9300: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70  ed to obtain a p
9310: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
9320: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9330: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65  object associate
9340: 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  d with a particu
9350: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
9360: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
9370: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
9380: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
9390: 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  TER]..**.** <li>
93a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a  [[SQLITE_FCNTL_J
93b0: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d  OURNAL_POINTER]]
93c0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
93d0: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
93e0: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
93f0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
9400: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
9410: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9420: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
9430: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a 6f  ated with the jo
9440: 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 68  urnal file (eith
9450: 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62  er.** the [rollb
9460: 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20  ack journal] or 
9470: 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 64  the [write-ahead
9480: 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 72   log]) for a par
9490: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
94a0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
94b0: 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54   See also [SQLIT
94c0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
94d0: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  NTER]..**.** <li
94e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
94f0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
9500: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
9510: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
9520: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9530: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9540: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9550: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9560: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9570: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
9580: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
9590: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
95a0: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
95b0: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
95c0: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
95d0: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
95e0: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
95f0: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
9600: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
9610: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
9620: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9630: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9640: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9650: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
9660: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
9670: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
9680: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
9690: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
96a0: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
96b0: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
96c0: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
96d0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
96e0: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
96f0: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
9700: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
9710: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
9720: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
9730: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9740: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9750: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
9760: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
9770: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
9780: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
9790: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
97a0: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
97b0: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
97c0: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
97d0: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
97e0: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
97f0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
9800: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
9810: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9820: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9830: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9840: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
9850: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
9860: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
9870: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
9880: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
9890: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
98a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
98b0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
98c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
98d0: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
98e0: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
98f0: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9900: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
9910: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
9920: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
9930: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9940: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
9950: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
9960: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
9970: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
9980: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
9990: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
99a0: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
99b0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
99c0: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
99d0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
99e0: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
99f0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9a00: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9a10: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9a20: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
9a30: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9a40: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9a50: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
9a60: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9a70: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9a80: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9a90: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9aa0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9ab0: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9ac0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9ad0: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9ae0: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9af0: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9b00: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
9b10: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
9b20: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9b30: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9b40: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9b50: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
9b60: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
9b70: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
9b80: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
9b90: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9ba0: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9bb0: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9bc0: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9bd0: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9be0: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9bf0: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9c00: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
9c10: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
9c20: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9c30: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9c40: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9c50: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
9c60: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
9c70: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
9c80: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
9c90: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9ca0: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9cb0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9cc0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9cd0: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9ce0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9cf0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9d00: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9d10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9d20: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9d30: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9d40: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9d50: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
9d60: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
9d70: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
9d80: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
9d90: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9da0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9db0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9dc0: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9dd0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9de0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9df0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9e00: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9e10: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9e20: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9e30: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9e40: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9e50: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9e60: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9e70: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9e80: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9e90: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9ea0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9eb0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9ec0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9ed0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9ee0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9ef0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9f00: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9f10: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9f20: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9f30: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9f40: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9f50: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9f60: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9f70: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9f80: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9f90: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9fa0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9fb0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9fc0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9fd0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9fe0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9ff0: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
a000: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
a010: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
a020: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
a030: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
a040: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
a050: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
a060: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
a070: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
a080: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
a090: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
a0a0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
a0b0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
a0c0: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
a0d0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
a0e0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
a0f0: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
a100: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
a110: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
a120: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
a130: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
a140: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
a150: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
a160: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
a170: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
a180: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a190: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
a1a0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
a1b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
a1c0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
a1d0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
a1e0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
a1f0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
a200: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
a210: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
a220: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a230: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a240: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a250: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a260: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
a270: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
a280: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a290: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a2a0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a2b0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a2c0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a2d0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a2e0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a2f0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a300: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a310: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a320: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a330: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a340: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a350: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a360: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a370: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a380: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a390: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a3a0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a3b0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a3c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a3d0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a3e0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a3f0: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a400: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a410: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a420: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a430: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a440: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a450: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a460: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a470: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a480: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a490: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a4a0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a4b0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a4c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a4d0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a4e0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a4f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a500: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a510: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a520: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a530: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a540: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a550: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a560: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a570: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a580: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a590: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a5a0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a5b0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a5c0: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a5d0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a5e0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a5f0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a600: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a610: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a620: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a630: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a640: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a650: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a660: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a670: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a680: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a690: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a6a0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a6b0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a6c0: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a6d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a6e0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a6f0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a700: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a710: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a720: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a730: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a740: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a750: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a760: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a770: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a780: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a790: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a7a0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a7b0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a7c0: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a7d0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a7e0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a7f0: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a800: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a810: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a820: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a830: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a840: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a850: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a860: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a870: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a880: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a890: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a8a0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a8b0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a8c0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a8d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a8e0: 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e  S_POINTER]].** ^
a8f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a900: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f  L_VFS_POINTER] o
a910: 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f  pcode finds a po
a920: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
a930: 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73  -level.** [VFSes
a940: 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75  ] currently in u
a950: 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d  se.  ^(The argum
a960: 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69  ent X in.** sqli
a970: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a980: 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c  (db,SQLITE_FCNTL
a990: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20  _VFS_POINTER,X) 
a9a0: 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79  must be.** of ty
a9b0: 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73  pe "[sqlite3_vfs
a9c0: 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63  ] **".  This opc
a9d0: 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58  odes will set *X
a9e0: 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72  .** to a pointer
a9f0: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65   to the top-leve
aa00: 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65  l VFS.)^.** ^Whe
aa10: 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74  n there are mult
aa20: 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69  iple VFS shims i
aa30: 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69  n the stack, thi
aa40: 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74  s opcode finds t
aa50: 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74  he.** upper-most
aa60: 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a   shim only..**.*
aa70: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
aa80: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
aa90: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
aaa0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
aab0: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
aac0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
aad0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
aae0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
aaf0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
ab00: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
ab10: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
ab20: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
ab30: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
ab40: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
ab50: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
ab60: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
ab70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ab80: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
ab90: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
aba0: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
abb0: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
abc0: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
abd0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
abe0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
abf0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
ac00: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
ac10: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
ac20: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
ac30: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
ac40: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
ac50: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
ac60: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
ac70: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
ac80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
ac90: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
aca0: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
acb0: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
acc0: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
acd0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
ace0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
acf0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
ad00: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
ad10: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
ad20: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
ad30: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
ad40: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
ad50: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
ad60: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
ad70: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
ad80: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
ad90: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
ada0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
adb0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
adc0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
add0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
ade0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
adf0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
ae00: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
ae10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ae20: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
ae30: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
ae40: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
ae50: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
ae60: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
ae70: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
ae80: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
ae90: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
aea0: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
aeb0: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
aec0: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c  atement if resul
aed0: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c  t string is NULL
aee0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e  , or that return
aef0: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
af00: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  he result string
af10: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   if the string i
af20: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e  s non-NULL..** ^
af30: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
af40: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
af50: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
af60: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
af70: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
af80: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
af90: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
afa0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
afb0: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
afc0: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
afd0: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
afe0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
aff0: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
b000: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
b010: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
b020: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
b030: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b040: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
b050: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
b060: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
b070: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
b080: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
b090: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
b0a0: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
b0b0: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
b0c0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
b0d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b0e0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
b0f0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
b100: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b110: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
b120: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
b130: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
b140: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
b150: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
b160: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
b170: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
b180: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
b190: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
b1a0: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
b1b0: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
b1c0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
b1d0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
b1e0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
b1f0: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
b200: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
b210: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
b220: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
b230: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
b240: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
b250: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
b260: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
b270: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
b280: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
b290: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
b2a0: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
b2b0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
b2c0: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
b2d0: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
b2e0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
b2f0: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
b300: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
b310: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
b320: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
b330: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
b340: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
b350: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
b360: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
b370: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
b380: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
b390: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b3a0: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
b3b0: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
b3c0: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
b3d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b3e0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
b3f0: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
b400: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
b410: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
b420: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
b430: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
b440: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
b450: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
b460: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b470: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
b480: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
b490: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
b4a0: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
b4b0: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
b4c0: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
b4d0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b4e0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
b4f0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
b500: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
b510: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
b520: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
b530: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
b540: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
b550: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
b560: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
b570: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
b580: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b590: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
b5a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b5b0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
b5c0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b5d0: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
b5e0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
b5f0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
b600: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
b610: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
b620: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
b630: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
b640: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
b650: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
b660: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
b670: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
b680: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b690: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
b6a0: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
b6b0: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
b6c0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
b6d0: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
b6e0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
b6f0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
b700: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
b710: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
b720: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
b730: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
b740: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
b750: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
b760: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
b770: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
b780: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
b790: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
b7a0: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
b7b0: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
b7c0: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
b7d0: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
b7e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
b7f0: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
b800: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b810: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
b820: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
b830: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
b840: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
b850: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
b860: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
b870: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
b880: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
b890: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
b8a0: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
b8b0: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
b8c0: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
b8d0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
b8e0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
b8f0: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
b900: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
b910: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
b920: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
b930: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
b940: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
b950: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
b960: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
b970: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
b980: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
b990: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b9a0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
b9b0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b9c0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
b9d0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
b9e0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
b9f0: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
ba00: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
ba10: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
ba20: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
ba30: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
ba40: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
ba50: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
ba60: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
ba70: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
ba80: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
ba90: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
baa0: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
bab0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bac0: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
bad0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
bae0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
baf0: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
bb00: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
bb10: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
bb20: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
bb30: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
bb40: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
bb50: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
bb60: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
bb70: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
bb80: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
bb90: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
bba0: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
bbb0: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
bbc0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
bbd0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
bbe0: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
bbf0: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  efined..**.** <l
bc00: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bc10: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20  _WAL_BLOCK]].** 
bc20: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bc30: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20  L_WAL_BLOCK] is 
bc40: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
bc50: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69  VFS layer that i
bc60: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64  t might.** be ad
bc70: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c  vantageous to bl
bc80: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  ock on the next 
bc90: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20  WAL lock if the 
bca0: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65  lock is not imme
bcb0: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c  diately.** avail
bcc0: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73  able.  The WAL s
bcd0: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20  ubsystem issues 
bce0: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69  this signal duri
bcf0: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75  ng rare.** circu
bd00: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65  mstances in orde
bd10: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c  r to fix a probl
bd20: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79  em with priority
bd30: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41   inversion..** A
bd40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
bd50: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  ld <em>not</em> 
bd60: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  use this file-co
bd70: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ntrol..**.** <li
bd80: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bd90: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20  ZIPVFS]].** The 
bda0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
bdb0: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20  PVFS] opcode is 
bdc0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a  implemented by z
bdd0: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20  ipvfs only. All 
bde0: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f  other.** VFS sho
bdf0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
be00: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74  E_NOTFOUND for t
be10: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a  his opcode..**.*
be20: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
be30: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68  CNTL_RBU]].** Th
be40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
be50: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  RBU] opcode is i
be60: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
be70: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73  e special VFS us
be80: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55  ed by.** the RBU
be90: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e   extension only.
bea0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20    All other VFS 
beb0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
bec0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
bed0: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65  r.** this opcode
bee0: 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .  .** </ul>.*/.
bef0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bf00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
bf10: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
bf20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bf30: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
bf40: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
bf50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bf60: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
bf70: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
bf80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bf90: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
bfa0: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
bfb0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bfc0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
bfd0: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
bfe0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bff0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
c000: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
c010: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
c020: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
c030: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
c040: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
c050: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
c060: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
c070: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c080: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
c090: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
c0a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
c0b0: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
c0c0: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
c0d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
c0e0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
c0f0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
c100: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
c110: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
c120: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
c130: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
c140: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
c150: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
c160: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
c170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
c180: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
c190: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
c1a0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
c1b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c1c0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
c1d0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
c1e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c1f0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
c200: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
c210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c220: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
c230: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
c240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c250: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
c260: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
c270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c280: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
c290: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
c2a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c2b0: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
c2c0: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69          22.#defi
c2d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c2e0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
c2f0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e         23.#defin
c300: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
c310: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20  AL_BLOCK        
c320: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65        24.#define
c330: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49   SQLITE_FCNTL_ZI
c340: 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20  PVFS            
c350: 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20       25.#define 
c360: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
c370: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c380: 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53      26.#define S
c390: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
c3a0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
c3b0: 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51     27.#define SQ
c3c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
c3d0: 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  AL_POINTER      
c3e0: 20 20 32 38 0a 0a 2f 2a 20 64 65 70 72 65 63 61    28../* depreca
c3f0: 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65  ted names */.#de
c400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
c410: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c420: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
c430: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
c440: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
c450: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
c460: 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46  LE      SQLITE_F
c470: 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_SET_LOCKPRO
c480: 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53  XYFILE.#define S
c490: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
c4a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c               SQL
c4b0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45  ITE_FCNTL_LAST_E
c4c0: 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  RRNO.../*.** CAP
c4d0: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e  I3REF: Mutex Han
c4e0: 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  dle.**.** The mu
c4f0: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
c500: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
c510: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
c520: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
c530: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
c540: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
c550: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
c560: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
c570: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
c580: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
c590: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
c5a0: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
c5b0: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
c5c0: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
c5d0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
c5e0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
c5f0: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
c600: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
c610: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
c620: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
c630: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
c640: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
c650: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
c660: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
c670: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
c680: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
c690: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
c6a0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
c6b0: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
c6c0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
c6d0: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
c6e0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
c6f0: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
c700: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
c710: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
c720: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
c730: 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65  ile system".  Se
c740: 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20  e.** the [VFS | 
c750: 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  VFS documentatio
c760: 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69  n] for further i
c770: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
c780: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
c790: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
c7a0: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
c7b0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
c7c0: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
c7d0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
c7e0: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
c7f0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
c800: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
c810: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
c820: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
c830: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
c840: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
c850: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
c860: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
c870: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
c880: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
c890: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
c8a0: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
c8b0: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
c8c0: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
c8d0: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
c8e0: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
c8f0: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
c900: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
c910: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
c920: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
c930: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
c940: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
c950: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
c960: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
c970: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
c980: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
c990: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
c9a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
c9b0: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
c9c0: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
c9d0: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
c9e0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
c9f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
ca00: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
ca10: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
ca20: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
ca30: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
ca40: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
ca50: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
ca60: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
ca70: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
ca80: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
ca90: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
caa0: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
cab0: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
cac0: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
cad0: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
cae0: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
caf0: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
cb00: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
cb10: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
cb20: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
cb30: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
cb40: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
cb50: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
cb60: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
cb70: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
cb80: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
cb90: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
cba0: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
cbb0: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
cbc0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
cbd0: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
cbe0: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
cbf0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
cc00: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
cc10: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
cc20: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
cc30: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
cc40: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
cc50: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
cc60: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
cc70: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
cc80: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
cc90: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  modules..**.** [
cca0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
ccb0: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  en]].** ^SQLite 
ccc0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
ccd0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
cce0: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
ccf0: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
cd00: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
cd10: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
cd20: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
cd30: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20  hname() with an 
cd40: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20  optional suffix 
cd50: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20  added..** ^If a 
cd60: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20  suffix is added 
cd70: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  to the zFilename
cd80: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77   parameter, it w
cd90: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f  ill.** consist o
cda0: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63  f a single "-" c
cdb0: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65  haracter followe
cdc0: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61  d by no more tha
cdd0: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d  n.** 11 alphanum
cde0: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20  eric and/or "-" 
cdf0: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e  characters..** ^
ce00: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
ce10: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
ce20: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
ce30: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
ce40: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
ce50: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
ce60: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
ce70: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
ce80: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
ce90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
cea0: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
ceb0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
cec0: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
ced0: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
cee0: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
cef0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
cf00: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
cf10: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
cf20: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  to xOpen is a NU
cf30: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
cf40: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
cf50: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
cf60: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
cf70: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e  the file.  ^When
cf80: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69  ever the .** xFi
cf90: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
cfa0: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c   is NULL it will
cfb0: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73   also be the cas
cfc0: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c  e that the.** fl
cfd0: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69  ags parameter wi
cfe0: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ll include [SQLI
cff0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d000: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  CLOSE]..**.** Th
d010: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d020: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
d030: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
d040: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
d050: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
d060: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
d070: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
d080: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
d090: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
d0a0: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
d0b0: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
d0c0: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
d0d0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
d0e0: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
d0f0: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a  PEN_CREATE]. .**
d100: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
d110: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
d120: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
d130: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
d140: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
d150: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
d160: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
d170: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
d180: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53  e set..**.** ^(S
d190: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
d1a0: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
d1b0: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
d1c0: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
d1d0: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
d1e0: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
d1f0: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
d200: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
d210: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
d220: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
d230: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
d240: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
d250: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d260: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
d270: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d280: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
d290: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d2a0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
d2b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d2c0: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
d2d0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d2e0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
d2f0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
d300: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d310: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  WAL].** </ul>)^.
d320: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
d330: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
d340: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
d350: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
d360: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
d370: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
d380: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
d390: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
d3a0: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
d3b0: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
d3c0: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
d3d0: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
d3e0: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
d3f0: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
d400: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
d410: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
d420: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
d430: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
d440: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
d450: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
d460: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
d470: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
d480: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
d490: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
d4a0: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
d4b0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
d4c0: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
d4d0: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
d4e0: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
d4f0: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
d500: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
d510: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
d520: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
d530: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
d540: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
d550: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
d560: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
d570: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
d580: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
d590: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
d5a0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
d5b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
d5c0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
d5d0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
d5e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
d5f0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
d600: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
d610: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
d620: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
d630: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20  s closed.  ^The 
d640: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
d650: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77  ETEONCLOSE].** w
d660: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54  ill be set for T
d670: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e  EMP databases an
d680: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73  d their journals
d690: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64  , transient.** d
d6a0: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75  atabases, and su
d6b0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
d6c0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
d6d0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
d6e0: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  ag is always use
d6f0: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e  d in conjunction
d700: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
d710: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d720: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72  ] flag, which ar
d730: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a  e both directly.
d740: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20  ** analogous to 
d750: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f  the O_EXCL and O
d760: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20  _CREAT flags of 
d770: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29  the POSIX open()
d780: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51  .** API.  The SQ
d790: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
d7a0: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70  IVE flag, when p
d7b0: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a  aired with the .
d7c0: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ** SQLITE_OPEN_C
d7d0: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74  REATE, is used t
d7e0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
d7f0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61  file should alwa
d800: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64  ys.** be created
d810: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73  , and that it is
d820: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20   an error if it 
d830: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a  already exists..
d840: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c  ** It is <i>not<
d850: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69  /i> used to indi
d860: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68  cate the file sh
d870: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a  ould be opened .
d880: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
d890: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e   access..**.** ^
d8a0: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
d8b0: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
d8c0: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
d8d0: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
d8e0: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
d8f0: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
d900: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
d910: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
d920: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
d930: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
d940: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
d950: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
d960: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
d970: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
d980: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
d990: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
d9a0: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
d9b0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
d9c0: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
d9d0: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
d9e0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
d9f0: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
da00: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
da10: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
da20: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
da30: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
da40: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
da50: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
da60: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
da70: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
da80: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
da90: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
daa0: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
dab0: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
dac0: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
dad0: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
dae0: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65  Access]].** ^The
daf0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
db00: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
db10: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
db20: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
db30: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
db40: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
db50: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
db60: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
db70: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
db80: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
db90: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
dba0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
dbb0: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
dbc0: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
dbd0: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
dbe0: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
dbf0: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
dc00: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
dc10: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
dc20: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
dc30: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
dc40: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
dc50: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
dc60: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
dc70: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20  ame.  The exact 
dc80: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
dc90: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
dca0: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
dcb0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
dcc0: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  th  methods. If 
dcd0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
dce0: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
dcf0: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
dd00: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
dd10: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
dd20: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
dd30: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
dd40: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
dd50: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
dd60: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
dd70: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
dd80: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
dd90: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
dda0: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
ddb0: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
ddc0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
ddd0: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
dde0: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65  (), xCurrentTime
ddf0: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
de00: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69  TimeInt64().** i
de10: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
de20: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
de30: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
de40: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
de50: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
de60: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
de70: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
de80: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
de90: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
dea0: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
deb0: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
dec0: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
ded0: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
dee0: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
def0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
df00: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
df10: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
df20: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
df30: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
df40: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
df50: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
df60: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
df70: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
df80: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
df90: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
dfa0: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e  n.  ^The xCurren
dfb0: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
dfc0: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
dfd0: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
dfe0: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
dff0: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a  te and time as.*
e000: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  * a floating poi
e010: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68  nt value..** ^Th
e020: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
e030: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74  t64() method ret
e040: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65  urns, as an inte
e050: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a  ger, the Julian.
e060: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75  ** Day Number mu
e070: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30  ltiplied by 8640
e080: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72  0000 (the number
e090: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
e0a0: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75   in .** a 24-hou
e0b0: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51  r day).  .** ^SQ
e0c0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
e0d0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
e0e0: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20  t64() method to 
e0f0: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a  get the current.
e100: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
e110: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20   if that method 
e120: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66  is available (if
e130: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f   iVersion is 2 o
e140: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e  r .** greater an
e150: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  d the function p
e160: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
e170: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c  LL) and will fal
e180: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75  l back.** to xCu
e190: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78  rrentTime() if x
e1a0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
e1b0: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  () is unavailabl
e1c0: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53  e..**.** ^The xS
e1d0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
e1e0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xGetSystemCall()
e1f0: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65  , and xNestSyste
e200: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  mCall() interfac
e210: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73  es.** are not us
e220: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65  ed by the SQLite
e230: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70   core.  These op
e240: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65  tional interface
e250: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a  s are provided.*
e260: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20  * by some VFSes 
e270: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65  to facilitate te
e280: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53  sting of the VFS
e290: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69   code. By overri
e2a0: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20  ding .** system 
e2b0: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74  calls with funct
e2c0: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63  ions under its c
e2d0: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70  ontrol, a test p
e2e0: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69  rogram can.** si
e2f0: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e  mulate faults an
e300: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  d error conditio
e310: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74  ns that would ot
e320: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69  herwise be diffi
e330: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73  cult.** or impos
e340: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e  sible to induce.
e350: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73    The set of sys
e360: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63  tem calls that c
e370: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
e380: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20  .** varies from 
e390: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68  one VFS to anoth
e3a0: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65  er, and from one
e3b0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
e3c0: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a  same VFS to the.
e3d0: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
e3e0: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
e3f0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
e400: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65   must be prepare
e410: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20  d for any.** or 
e420: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74  all of these int
e430: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55  erfaces to be NU
e440: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20  LL or for their 
e450: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e  behavior to chan
e460: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72  ge.** from one r
e470: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
e480: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
e490: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d  s must not attem
e4a0: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20  pt to access.** 
e4b0: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74  any of these met
e4c0: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72  hods if the iVer
e4d0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20  sion of the VFS 
e4e0: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a  is less than 3..
e4f0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
e500: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
e510: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64  lite3_vfs;.typed
e520: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
e530: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76  3_syscall_ptr)(v
e540: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c  oid);.struct sql
e550: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
e560: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
e570: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
e580: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
e590: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20  r (currently 3) 
e5a0: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
e5b0: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
e5c0: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
e5d0: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
e5e0: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
e5f0: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
e600: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
e610: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
e620: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
e630: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
e640: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
e650: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
e660: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
e670: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
e680: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
e690: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
e6a0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
e6b0: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
e6c0: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
e6d0: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
e6e0: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
e6f0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e700: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
e710: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
e720: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
e730: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
e740: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
e750: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
e760: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e770: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
e780: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
e790: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
e7a0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e7b0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
e7c0: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
e7d0: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
e7e0: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
e7f0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e800: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
e810: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
e820: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
e830: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(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 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
e860: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
e870: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
e880: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
e890: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
e8a0: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
e8b0: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
e8c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
e8d0: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
e8e0: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
e8f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
e900: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
e910: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
e920: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
e930: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
e940: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
e950: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
e960: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
e970: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
e980: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
e990: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
e9a0: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
e9b0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
e9c0: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
e9d0: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
e9e0: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
e9f0: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20  re in version 1 
ea00: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
ea10: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65  s object.  ** de
ea20: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65  finition.  Those
ea30: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65   that follow are
ea40: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f   added in versio
ea50: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a  n 2 or later.  *
ea60: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  /.  int (*xCurre
ea70: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
ea80: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
ea90: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
eaa0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
eab0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
eac0: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
ead0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
eae0: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54  s object..  ** T
eaf0: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66  hose below are f
eb00: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64  or version 3 and
eb10: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20   greater..  */. 
eb20: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65   int (*xSetSyste
eb30: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
eb40: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
eb50: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
eb60: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20  syscall_ptr);.  
eb70: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
eb80: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d  ptr (*xGetSystem
eb90: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
eba0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ebb0: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20  zName);.  const 
ebc0: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73  char *(*xNextSys
ebd0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
ebe0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ebf0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a  r *zName);.  /*.
ec00: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
ec10: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
ec20: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68  rsions 1 through
ec30: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   3 of the sqlite
ec40: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
ec50: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
ec60: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
ec70: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  future versions.
ec80: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
ec90: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
eca0: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
ecb0: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
ecc0: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
ecd0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
ece0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
ecf0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
ed00: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
ed10: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
ed20: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
ed30: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
ed40: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
ed50: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
ed60: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
ed70: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
ed80: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
ed90: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
eda0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
edb0: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
edc0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
edd0: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
ede0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
edf0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
ee00: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
ee10: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
ee20: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
ee30: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
ee40: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
ee50: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
ee60: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
ee70: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
ee80: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
ee90: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
eea0: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
eeb0: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
eec0: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
eed0: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
eee0: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
eef0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
ef00: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
ef10: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
ef20: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
ef30: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
ef40: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
ef50: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
ef60: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
ef70: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
ef80: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
ef90: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
efa0: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
efb0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
efc0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
efd0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
efe0: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
eff0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
f000: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
f010: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
f020: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
f030: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
f040: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
f050: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
f060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
f070: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
f080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f090: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
f0a0: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
f0b0: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
f0c0: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
f0d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
f0e0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
f0f0: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
f100: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
f110: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
f120: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
f130: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
f140: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
f150: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
f160: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
f170: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
f180: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
f190: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
f1a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
f1b0: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
f1c0: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
f1d0: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
f1e0: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
f1f0: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
f200: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
f210: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
f220: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
f230: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
f240: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f250: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
f260: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
f270: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f280: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
f290: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
f2a0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
f2b0: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
f2c0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
f2d0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
f2e0: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
f2f0: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
f300: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
f310: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
f320: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
f330: 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f   on the correspo
f340: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
f350: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f360: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
f370: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
f380: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
f390: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
f3a0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
f3b0: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
f3c0: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
f3d0: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
f3e0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
f3f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f400: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
f410: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
f420: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
f430: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
f440: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
f450: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
f460: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
f470: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
f480: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
f490: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
f4a0: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
f4b0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
f4c0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f4d0: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
f4e0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
f4f0: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
f500: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
f510: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
f520: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
f530: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
f540: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
f550: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
f560: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
f570: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
f580: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f590: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
f5a0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
f5b0: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
f5c0: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
f5d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
f5e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f5f0: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
f600: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
f610: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
f620: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
f630: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
f640: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
f650: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
f660: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
f670: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f680: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
f690: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
f6a0: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
f6b0: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
f6c0: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
f6d0: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
f6e0: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
f6f0: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
f700: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
f710: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
f720: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
f730: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
f740: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
f750: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
f760: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f770: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
f780: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
f790: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
f7a0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
f7b0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
f7c0: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
f7d0: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
f7e0: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
f7f0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
f800: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
f810: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
f820: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
f830: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
f840: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f850: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
f860: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
f870: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
f880: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
f890: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
f8a0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
f8b0: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
f8c0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
f8d0: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
f8e0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
f8f0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
f900: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
f910: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
f920: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
f930: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
f940: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
f950: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
f960: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
f970: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
f980: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
f990: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
f9a0: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
f9b0: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
f9c0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
f9d0: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
f9e0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
f9f0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fa00: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fa10: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
fa20: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
fa30: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
fa40: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
fa50: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fa60: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
fa70: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
fa80: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
fa90: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
faa0: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
fab0: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
fac0: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
fad0: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
fae0: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
faf0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
fb00: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
fb10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
fb20: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
fb30: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
fb40: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
fb50: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
fb60: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
fb70: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
fb80: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
fb90: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
fba0: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
fbb0: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
fbc0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
fbd0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
fbe0: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
fbf0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
fc00: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
fc10: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
fc20: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fc30: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
fc40: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
fc50: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
fc60: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
fc70: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
fc80: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
fc90: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
fca0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
fcb0: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
fcc0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
fcd0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
fce0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fcf0: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
fd00: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
fd10: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
fd20: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
fd30: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
fd40: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
fd50: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
fd60: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
fd70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fd80: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
fd90: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
fda0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
fdb0: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
fdc0: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
fdd0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
fde0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
fdf0: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
fe00: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
fe10: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
fe20: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
fe30: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
fe40: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
fe50: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
fe60: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
fe70: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
fe80: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
fe90: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
fea0: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
feb0: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
fec0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fed0: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
fee0: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
fef0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
ff00: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
ff10: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
ff20: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
ff30: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
ff40: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
ff50: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
ff60: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
ff70: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
ff80: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
ff90: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
ffa0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ffb0: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
ffc0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
ffd0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
ffe0: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
fff0: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
10000 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
10010 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
10020 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
10030 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
10040 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
10050 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10060 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
10070 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
10080 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
10090 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
100a0 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
100b0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
100c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
100d0 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
100e0 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
100f0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
10100 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
10110 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
10120 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
10130 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10140 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
10150 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
10160 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
10170 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
10180 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
10190 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
101a0 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
101b0 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
101c0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
101d0 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
101e0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
101f0 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
10200 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
10210 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
10220 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
10230 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
10240 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
10250 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
10260 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10270 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
10280 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
10290 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
102a0 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
102b0 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
102c0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
102d0 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
102e0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
102f0 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
10300 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10310 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
10320 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
10330 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10340 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
10350 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
10360 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
10370 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
10380 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
10390 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
103a0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
103b0 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
103c0 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
103d0 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
103e0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
103f0 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
10400 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
10410 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
10420 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
10430 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
10440 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
10450 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
10460 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
10470 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
10480 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
10490 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
104a0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
104b0 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
104c0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
104d0 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
104e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
104f0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
10500 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
10510 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
10520 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
10530 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
10540 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
10550 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
10560 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
10570 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
10580 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
10590 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
105a0 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
105b0 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
105c0 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lure..*/.SQLITE_
105d0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
105e0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 69  TDCALL sqlite3_i
105f0 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
10600 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
10610 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
10620 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10630 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
10640 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
10650 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 73 5f  CALL sqlite3_os_
10660 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49  init(void);.SQLI
10670 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
10680 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
10690 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
106a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
106b0 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
106c0 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
106d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
106e0 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
106f0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
10700 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
10710 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
10720 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
10730 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
10740 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
10750 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
10760 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
10770 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
10780 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
10790 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
107a0 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
107b0 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
107c0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
107d0 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
107e0 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
107f0 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
10800 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
10810 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
10820 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c  l needs..**.** <
10830 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  b>The sqlite3_co
10840 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10850 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
10860 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74  fe. The applicat
10870 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75  ion.** must ensu
10880 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
10890 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
108a0 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
108b0 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
108c0 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
108d0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
108e0 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20  ning.</b>.**.** 
108f0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10900 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ig() interface.*
10910 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
10920 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
10930 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
10940 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
10950 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10960 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
10970 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
10980 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
10990 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
109a0 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
109b0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
109c0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
109d0 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
109e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
109f0 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
10a00 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
10a10 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
10a20 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
10a30 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
10a40 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
10a50 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
10a60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
10a70 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
10a80 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
10a90 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
10aa0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
10ab0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
10ac0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
10ad0 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
10ae0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10af0 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
10b00 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
10b10 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
10b20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
10b30 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
10b40 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
10b50 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
10b60 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
10b70 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
10b80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10b90 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
10ba0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10bb0 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
10bc0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
10bd0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
10be0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
10bf0 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
10c00 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
10c10 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
10c20 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
10c30 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
10c40 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
10c50 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53  rror code]..*/.S
10c60 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
10c70 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74  LITE_CDECL sqlit
10c80 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
10c90 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
10ca0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
10cb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10cc0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
10cd0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
10ce0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
10cf0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
10d00 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
10d10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
10d20 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
10d30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10d40 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
10d50 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
10d60 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10d70 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
10d80 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
10d90 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
10da0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
10db0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
10dc0 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
10dd0 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
10de0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
10df0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
10e00 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
10e10 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
10e20 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
10e30 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
10e40 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
10e50 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
10e60 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
10e70 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
10e80 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
10e90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10ea0 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
10eb0 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
10ec0 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
10ed0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
10ee0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
10ef0 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
10f00 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
10f10 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
10f20 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
10f30 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
10f40 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
10f50 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
10f60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
10f70 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 20  nt SQLITE_CDECL 
10f80 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10f90 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
10fa0 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
10fb0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
10fc0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
10fd0 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  tines.**.** An i
10fe0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
10ff0 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
11000 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
11010 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
11020 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
11030 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11040 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
11050 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
11060 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
11070 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
11080 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
11090 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
110a0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
110b0 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
110c0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
110d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
110e0 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
110f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11100 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
11110 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20  NFIG_MALLOC] or 
11120 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
11130 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20  ETMALLOC].  .** 
11140 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
11150 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
11160 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
11170 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
11180 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
11190 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
111a0 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63  OC]).** during c
111b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
111c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
111d0 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
111e0 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
111f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
11200 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74  system for SQLit
11210 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
11220 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d   of its.** dynam
11230 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
11240 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
11250 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
11260 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c  th several [buil
11270 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
11280 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20  cators].** that 
11290 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64  are perfectly ad
112a0 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
112b0 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
112c0 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
112d0 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
112e0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
112f0 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
11300 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
11310 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
11320 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
11330 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
11340 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
11350 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
11360 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
11370 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
11380 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
11390 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
113a0 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
113b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
113c0 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
113d0 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
113e0 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
113f0 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
11400 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
11410 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
11420 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
11430 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
11440 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c  .** The xMalloc,
11450 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78   xRealloc, and x
11460 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
11470 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
11480 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  ** malloc(), rea
11490 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
114a0 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
114b0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
114c0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c  library..** ^SQL
114d0 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
114e0 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61  hat the second a
114f0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52  rgument to.** xR
11500 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73  ealloc is always
11510 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65   a value returne
11520 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c  d by a prior cal
11530 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a  l to xRoundup..*
11540 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
11550 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
11560 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
11570 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11580 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
11590 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
115a0 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
115b0 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
115c0 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
115d0 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
115e0 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
115f0 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
11600 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
11610 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
11620 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
11630 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
11640 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
11650 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
11660 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
11670 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
11680 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
11690 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
116a0 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
116b0 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
116c0 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
116d0 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
116e0 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
116f0 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
11700 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
11710 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
11720 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
11730 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
11740 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
11750 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
11760 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
11770 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
11780 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
11790 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
117a0 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
117b0 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
117c0 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
117d0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
117e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
117f0 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
11800 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
11810 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
11820 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11830 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tor.  For exampl
11840 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
11850 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
11860 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
11870 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
11880 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
11890 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
118a0 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
118b0 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
118c0 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
118d0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
118e0 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
118f0 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
11900 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
11910 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
11920 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
11930 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
11940 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
11950 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
11960 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
11970 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
11980 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
11990 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
119a0 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
119b0 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
119c0 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
119d0 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
119e0 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
119f0 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
11a00 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
11a10 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
11a20 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
11a30 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
11a40 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
11a50 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
11a60 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
11a70 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
11a80 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
11a90 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
11aa0 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
11ab0 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
11ac0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
11ad0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
11ae0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11af0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
11b00 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
11b10 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
11b20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
11b30 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
11b40 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
11b50 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
11b60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
11b70 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
11b80 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
11b90 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
11ba0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
11bb0 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
11bc0 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
11bd0 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
11be0 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
11bf0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
11c00 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
11c10 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
11c20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
11c30 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
11c40 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
11c50 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
11c60 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11c70 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
11c80 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
11c90 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11ca0 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
11cb0 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
11cc0 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
11cd0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
11ce0 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
11cf0 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
11d00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
11d10 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
11d20 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
11d30 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
11d40 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
11d50 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
11d60 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
11d70 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
11d80 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
11d90 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
11da0 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
11db0 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
11dc0 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
11dd0 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
11de0 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
11df0 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
11e00 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
11e10 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
11e20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
11e30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
11e40 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
11e50 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
11e60 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
11e70 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
11e80 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
11e90 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
11ea0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
11eb0 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
11ec0 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
11ed0 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
11ee0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11ef0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
11f00 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
11f10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11f20 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
11f30 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
11f40 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
11f50 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
11f60 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
11f70 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
11f80 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
11f90 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
11fa0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11fb0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
11fc0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
11fd0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
11fe0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
11ff0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
12000 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
12010 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
12020 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
12030 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
12040 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
12050 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
12060 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
12070 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
12080 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
12090 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
120a0 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
120b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
120c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
120d0 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
120e0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
120f0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
12100 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
12110 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
12120 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
12130 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
12140 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
12150 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
12160 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
12170 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
12180 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
12190 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
121a0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
121b0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
121c0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
121d0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
121e0 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
121f0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
12200 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
12210 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
12220 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
12230 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
12240 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
12250 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
12260 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
12270 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
12280 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
12290 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
122a0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
122b0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
122c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
122d0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
122e0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
122f0 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
12300 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
12310 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
12320 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
12330 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
12340 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12350 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
12360 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
12370 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
12380 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
12390 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
123a0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
123b0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
123c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
123d0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
123e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
123f0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
12400 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
12410 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
12420 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12430 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
12440 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12450 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12460 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
12470 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
12480 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
12490 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
124a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
124b0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
124c0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
124d0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
124e0 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
124f0 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
12500 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
12510 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12520 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
12530 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
12540 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
12550 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
12560 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
12570 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
12580 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
12590 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
125a0 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
125b0 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
125c0 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
125d0 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
125e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
125f0 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
12600 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
12610 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12620 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
12630 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
12640 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
12650 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
12660 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
12670 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
12680 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
12690 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
126a0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
126b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
126c0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
126d0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
126e0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
126f0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
12700 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
12710 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
12720 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
12730 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12740 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
12750 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12760 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
12770 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
12780 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
12790 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
127a0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
127b0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
127c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
127d0 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
127e0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
127f0 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
12800 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
12810 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
12820 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
12830 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
12840 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
12850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12860 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
12870 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
12880 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
12890 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
128a0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
128b0 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
128c0 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
128d0 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
128e0 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
128f0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
12900 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12910 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
12920 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
12930 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
12940 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
12950 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
12960 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
12970 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
12980 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
12990 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
129a0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
129b0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
129c0 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
129d0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
129e0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
129f0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
12a00 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12a10 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
12a20 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
12a30 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
12a40 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
12a50 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
12a60 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
12a70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12a80 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
12a90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
12aa0 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
12ab0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
12ac0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
12ad0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12ae0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
12af0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12b00 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
12b10 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12b20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12b30 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12b40 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  G_MALLOC option 
12b50 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12b60 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
12b70 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
12b80 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
12b90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
12ba0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
12bb0 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
12bc0 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
12bd0 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
12be0 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
12bf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12c00 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
12c10 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
12c20 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12c30 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
12c40 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
12c50 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
12c60 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
12c70 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
12c80 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
12c90 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12ca0 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
12cb0 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
12cc0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
12cd0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
12ce0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12cf0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
12d00 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
12d10 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
12d20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
12d30 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12d40 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  _GETMALLOC optio
12d50 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
12d60 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
12d70 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
12d80 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
12d90 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12da0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12db0 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73  cture..** The [s
12dc0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12dd0 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
12de0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
12df0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
12e00 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
12e10 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12e20 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
12e30 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
12e40 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
12e50 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
12e60 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
12e70 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
12e80 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
12e90 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
12ea0 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
12eb0 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
12ec0 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
12ed0 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
12ee0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12ef0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
12f00 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12f10 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
12f20 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
12f30 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
12f40 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65  ATUS option take
12f50 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
12f60 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a  t of type int,.*
12f70 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  * interpreted as
12f80 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63   a boolean, whic
12f90 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
12fa0 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
12fb0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72  tion of.** memor
12fc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
12fd0 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
12fe0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12ff0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
13000 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68  .** disabled, th
13010 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  e following SQLi
13020 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
13030 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
13040 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
13050 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
13060 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
13070 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
13080 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
13090 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
130a0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
130b0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
130c0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
130d0 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a  te3_status64()].
130e0 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
130f0 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
13100 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
13110 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
13120 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
13130 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
13140 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
13150 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
13160 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
13170 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
13180 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
13190 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
131a0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
131b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
131c0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
131d0 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
131e0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
131f0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
13200 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13210 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65  RATCH option spe
13220 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
13230 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a  memory buffer.**
13240 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
13250 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63 68   use for scratch
13260 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72   memory.  ^(Ther
13270 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
13280 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49  ments.** to SQLI
13290 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
132a0 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  H:  A pointer an
132b0 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
132c0 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
132d0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
132e0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
132f0 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  ons will be.** d
13300 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f  rawn, the size o
13310 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61  f each scratch a
13320 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a  llocation (sz),.
13330 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ** and the maxim
13340 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72  um number of scr
13350 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
13360 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66   (N).)^.** The f
13370 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
13380 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
13390 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
133a0 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
133b0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
133c0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
133d0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
133e0 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68   not use more th
133f0 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62  an one scratch b
13400 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61  uffers per threa
13410 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  d..** ^SQLite wi
13420 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73 74  ll never request
13430 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
13440 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
13450 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
13460 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
13470 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   size..** ^If SQ
13480 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
13490 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73   additional.** s
134a0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
134b0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
134c0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f  vided by this co
134d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
134e0 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71  on, then .** [sq
134f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13500 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20  will be used to 
13510 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
13520 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20  y needed.<p>.** 
13530 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63  ^When the applic
13540 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61  ation provides a
13550 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72  ny amount of scr
13560 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e  atch memory usin
13570 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  g.** SQLITE_CONF
13580 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69  IG_SCRATCH, SQLi
13590 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65  te avoids unnece
135a0 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b  ssary large.** [
135b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68  sqlite3_malloc|h
135c0 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d  eap allocations]
135d0 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65  ..** This can he
135e0 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66  lp [Robson proof
135f0 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20  |prevent memory 
13600 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
13610 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70  res] due to heap
13620 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  .** fragmentatio
13630 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20  n in low-memory 
13640 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
13650 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
13660 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13670 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
13680 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
13690 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
136a0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
136b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
136c0 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  HE option specif
136d0 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f  ies a memory poo
136e0 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  l.** that SQLite
136f0 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65   can use for the
13700 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
13710 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
13720 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61  fault page.** ca
13730 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
13740 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
13750 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13760 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66  on is a no-op if
13770 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
13780 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
13790 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
137a0 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
137b0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
137c0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e  CONFIG_PCACHE2].
137d0 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
137e0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
137f0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
13800 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69  PAGECACHE: A poi
13810 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74  nter to.** 8-byt
13820 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  e aligned memory
13830 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a   (pMem), the siz
13840 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 63  e of each page c
13850 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a  ache line (sz),.
13860 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ** and the numbe
13870 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73  r of cache lines
13880 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
13890 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
138a0 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
138b0 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
138c0 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
138d0 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
138e0 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33  een 512 and 6553
138f0 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74  6) plus some ext
13900 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63  ra bytes for eac
13910 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
13920 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  .  ^The number o
13930 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65  f extra bytes ne
13940 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65  eded by the page
13950 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62   header.** can b
13960 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
13970 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ng [SQLITE_CONFI
13980 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e  G_PCACHE_HDRSZ].
13990 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  .** ^It is harml
139a0 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
139b0 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
139c0 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a  y,.** for the sz
139d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
139e0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63   larger than nec
139f0 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65  essary.  The pMe
13a00 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  m.** argument mu
13a10 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
13a20 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  ULL pointer or a
13a30 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
13a40 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
13a50 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
13a60 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
13a70 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69  N bytes, otherwi
13a80 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  se.** subsequent
13a90 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
13aa0 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e  efined..** ^When
13ab0 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c   pMem is not NUL
13ac0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73  L, SQLite will s
13ad0 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68 65  trive to use the
13ae0 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
13af0 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70  .** to satisfy p
13b00 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c  age cache needs,
13b10 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f   falling back to
13b20 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13b30 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65  ()] if.** a page
13b40 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c   cache line is l
13b50 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79  arger than sz by
13b60 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66  tes or if all of
13b70 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72   the pMem buffer
13b80 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65 64  .** is exhausted
13b90 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73  ..** ^If pMem is
13ba0 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e   NULL and N is n
13bb0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61  on-zero, then ea
13bc0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
13bd0 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61  ection.** does a
13be0 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61  n initial bulk a
13bf0 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61  llocation for pa
13c00 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a  ge cache memory.
13c10 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
13c20 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69  _malloc()] suffi
13c30 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68  cient for N cach
13c40 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20  e lines if N is 
13c50 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f  positive or.** o
13c60 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20  f -1024*N bytes 
13c70 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  if N is negative
13c80 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  , . ^If addition
13c90 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
13ca0 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
13cb0 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
13cc0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
13cd0 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f   initial.** allo
13ce0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c  cation, then SQL
13cf0 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
13d00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
13d10 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61  eparately for ea
13d20 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  ch.** additional
13d30 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64   cache line. </d
13d40 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13d50 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
13d60 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13d70 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
13d80 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
13d90 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
13da0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
13db0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
13dc0 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c  fer .** that SQL
13dd0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72  ite will use for
13de0 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
13df0 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
13e00 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62  ation needs.** b
13e10 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
13e20 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c  ided for by [SQL
13e30 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13e40 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49  CH] and.** [SQLI
13e50 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13e60 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51  CHE]..** ^The SQ
13e70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
13e80 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
13e90 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
13ea0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a  ite is compiled.
13eb0 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b  ** with either [
13ec0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
13ed0 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54  MSYS3] or [SQLIT
13ee0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
13ef0 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  ] and returns.**
13f00 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
13f10 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72  if invoked other
13f20 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  wise..** ^There 
13f30 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
13f40 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
13f50 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e  NFIG_HEAP:.** An
13f60 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
13f70 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
13f80 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
13f90 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
13fa0 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
13fb0 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
13fc0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13fd0 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
13fe0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
13ff0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
14000 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
14010 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
14020 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
14030 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
14040 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
14050 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
14060 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
14070 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
14080 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
14090 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
140a0 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
140b0 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
140c0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
140d0 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
140e0 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
140f0 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
14100 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
14110 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
14120 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14130 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
14140 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
14150 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
14160 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
14170 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
14180 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
14190 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
141a0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
141b0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
141c0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
141d0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
141e0 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
141f0 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
14200 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
14210 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
14220 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
14230 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
14240 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14250 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
14260 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14270 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
14280 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14290 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f  E_CONFIG_MUTEX o
142a0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
142b0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
142c0 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ich is a.** poin
142d0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
142e0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
142f0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14300 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
14310 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
14320 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69  cifies alternati
14330 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
14340 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
14350 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61  e used.** in pla
14360 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ce the mutex rou
14370 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
14380 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
14390 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
143a0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
143b0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
143c0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
143d0 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
143e0 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
143f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14400 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
14410 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14420 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
14430 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
14440 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
14450 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
14460 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
14470 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
14480 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
14490 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
144a0 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
144b0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
144c0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
144d0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
144e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
144f0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
14500 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
14510 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
14520 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
14530 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14540 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c  FIG_GETMUTEX]] <
14550 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14560 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
14570 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14580 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14590 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TEX option takes
145a0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
145b0 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
145c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
145d0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
145e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
145f0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
14600 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
14610 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14620 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
14630 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
14640 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
14650 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
14660 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
14670 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
14680 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
14690 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
146a0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
146b0 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
146c0 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
146d0 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
146e0 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
146f0 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
14700 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
14710 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
14720 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14730 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14740 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
14750 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14760 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
14770 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
14780 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
14790 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
147a0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
147b0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
147c0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
147d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
147e0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
147f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14800 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14810 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
14820 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
14830 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
14840 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14850 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
14860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14870 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
14880 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14890 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
148a0 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  DE option takes 
148b0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
148c0 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  at determine.** 
148d0 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65  the default size
148e0 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65   of lookaside me
148f0 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61  mory on each [da
14900 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14910 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  n]..** The first
14920 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
14930 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
14940 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
14950 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
14960 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
14970 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
14980 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
14990 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
149a0 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49  ction.)^  ^(SQLI
149b0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
149c0 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20  IDE.** sets the 
149d0 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
149e0 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
149f0 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
14a00 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
14a10 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c  * option to [sql
14a20 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
14a30 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
14a40 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
14a50 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
14a60 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
14a70 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
14a80 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
14a90 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14aa0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
14ab0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14ac0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
14ad0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14ae0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
14af0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14b00 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14b10 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
14b20 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
14b30 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14b40 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73  2] object.  This
14b50 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
14b60 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61  s.** the interfa
14b70 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70  ce to a custom p
14b80 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
14b90 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e  entation.)^.** ^
14ba0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
14bb0 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
14bc0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
14bd0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64  ds2] object.</dd
14be0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14bf0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14c00 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
14c10 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14c20 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
14c30 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14c40 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70  IG_GETPCACHE2 op
14c50 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14c60 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
14c70 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
14c80 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
14c90 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14ca0 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  2] object.  SQLi
14cb0 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20  te copies of.** 
14cc0 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 65  the current page
14cd0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
14ce0 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
14cf0 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
14d00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14d10 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e  ONFIG_LOG]] <dt>
14d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14d30 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54  G</dt>.** <dd> T
14d40 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14d50 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75  _LOG option is u
14d60 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
14d70 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67   the SQLite.** g
14d80 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67  lobal [error log
14d90 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49  ]..** (^The SQLI
14da0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
14db0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
14dc0 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e  rguments: a poin
14dd0 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63  ter to a.** func
14de0 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c  tion with a call
14df0 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f   signature of vo
14e00 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  id(*)(void*,int,
14e10 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a  const char*), .*
14e20 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20  * and a pointer 
14e30 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65  to void. ^If the
14e40 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
14e50 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69  r is not NULL, i
14e60 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  t is.** invoked 
14e70 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  by [sqlite3_log(
14e80 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61  )] to process ea
14e90 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74  ch logging event
14ea0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75  .  ^If the.** fu
14eb0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
14ec0 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c  s NULL, the [sql
14ed0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65  ite3_log()] inte
14ee0 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20  rface becomes a 
14ef0 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76  no-op..** ^The v
14f00 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74  oid pointer that
14f10 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
14f20 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54  rgument to SQLIT
14f30 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a  E_CONFIG_LOG is.
14f40 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  ** passed throug
14f50 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  h as the first p
14f60 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
14f70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
14f80 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
14f90 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20  nction whenever 
14fa0 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73  that function is
14fb0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20   invoked.  ^The 
14fc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14fd0 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65   to.** the logge
14fe0 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  r function is a 
14ff0 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73  copy of the firs
15000 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
15010 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
15020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  .** [sqlite3_log
15030 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20  ()] call and is 
15040 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61  intended to be a
15050 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
15060 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  r an.** [extende
15070 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20  d result code]. 
15080 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
15090 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
150a0 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a  the logger is.**
150b0 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74   log message aft
150c0 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69  er formatting vi
150d0 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  a [sqlite3_snpri
150e0 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53  ntf()]..** The S
150f0 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e  QLite logging in
15100 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
15110 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f  eentrant; the lo
15120 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gger function.**
15130 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
15140 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
15150 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79  t not invoke any
15160 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
15170 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69  e..** In a multi
15180 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
15190 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69  ation, the appli
151a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
151b0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
151c0 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  n must be thread
151d0 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  safe. </dd>.**.*
151e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
151f0 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_URI]] <dt>SQLI
15200 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a  TE_CONFIG_URI.**
15210 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54   <dd>^(The SQLIT
15220 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74  E_CONFIG_URI opt
15230 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15240 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
15250 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e  ype int..** If n
15260 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52  on-zero, then UR
15270 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
15280 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
15290 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
152a0 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65   is zero,.** the
152b0 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
152c0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
152d0 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68  led.)^ ^If URI h
152e0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
152f0 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20  lly.** enabled, 
15300 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61  all filenames pa
15310 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
15320 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
15330 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a  e3_open_v2()],.*
15340 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
15350 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
15360 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
15370 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
15380 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
15390 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
153a0 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
153b0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
153c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
153d0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
153e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
153f0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
15400 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69  opened. ^If it i
15410 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
15420 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
15430 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
15440 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
15450 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
15460 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
15470 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
15480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15490 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42  n is opened. ^(B
154a0 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
154b0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
154c0 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
154d0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
154e0 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
154f0 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
15500 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
15510 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
15520 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a  ol defined.)^.**
15530 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15540 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
15550 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
15560 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15570 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
15580 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15590 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
155a0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70  NG_INDEX_SCAN op
155b0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
155c0 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61  gle integer.** a
155d0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
155e0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
155f0 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64  a boolean in ord
15600 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  er to enable or 
15610 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75  disable.** the u
15620 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
15630 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
15640 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74  table scans in t
15650 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
15660 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  er..** ^The defa
15670 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64  ult setting is d
15680 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20  etermined.** by 
15690 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f  the [SQLITE_ALLO
156a0 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  W_COVERING_INDEX
156b0 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SCAN] compile-t
156c0 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69  ime option, or i
156d0 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61  s "on".** if tha
156e0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
156f0 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ption is omitted
15700 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79  ..** The ability
15710 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20   to disable the 
15720 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
15730 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
15740 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20   table scans.** 
15750 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20  is because some 
15760 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65  incorrectly code
15770 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61  d legacy applica
15780 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66  tions might malf
15790 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20  unction.** when 
157a0 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
157b0 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
157c0 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
157d0 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
157e0 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
157f0 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
15800 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
15810 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
15820 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
15830 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
15840 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
15850 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
15860 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15870 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
15880 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15890 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
158a0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
158b0 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
158c0 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
158d0 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
158e0 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
158f0 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
15900 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
15910 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
15920 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
15930 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
15940 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
15950 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64   no-ops..** </dd
15960 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15970 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d  _CONFIG_SQLLOG]]
15980 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
15990 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20  ONFIG_SQLLOG.** 
159a0 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
159b0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
159c0 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63  e if sqlite is c
159d0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
159e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
159f0 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70  LE_SQLLOG] pre-p
15a00 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
15a10 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73  efined. The firs
15a20 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  t argument shoul
15a30 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65  d.** be a pointe
15a40 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  r to a function 
15a50 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28  of type void(*)(
15a60 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63  void*,sqlite3*,c
15a70 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
15a80 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
15a90 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70  should be of typ
15aa0 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63  e (void*). The c
15ab0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
15ac0 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72  ed by the librar
15ad0 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65  y.** in three se
15ae0 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61  parate circumsta
15af0 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64  nces, identified
15b00 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61   by the value pa
15b10 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66  ssed as the.** f
15b20 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e  ourth parameter.
15b30 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
15b40 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74  arameter is 0, t
15b50 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
15b60 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70   connection.** p
15b70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
15b80 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73  ond argument has
15b90 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65   just been opene
15ba0 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67  d. The third arg
15bb0 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20  ument.** points 
15bc0 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74  to a buffer cont
15bd0 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20  aining the name 
15be0 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  of the main data
15bf0 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68  base file. If th
15c00 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
15c10 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e  meter is 1, then
15c20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
15c30 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72  nt that the thir
15c40 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70  d parameter.** p
15c50 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73  oints to has jus
15c60 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e  t been executed.
15c70 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72   Or, if the four
15c80 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15c90 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63  2, then.** the c
15ca0 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20  onnection being 
15cb0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
15cc0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
15cd0 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20  s being closed. 
15ce0 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  The.** third par
15cf0 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64  ameter is passed
15d00 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61   NULL In this ca
15d10 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  se.  An example 
15d20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a  of using this.**
15d30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15d40 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65  ption can be see
15d50 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73  n in the "test_s
15d60 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20  qllog.c" source 
15d70 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63  file in.** the c
15d80 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20  anonical SQLite 
15d90 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64  source tree.</dd
15da0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15db0 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15dc0 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
15dd0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15de0 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54  ZE.** <dd>^SQLIT
15df0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15e00 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d  ZE takes two 64-
15e10 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c  bit integer (sql
15e20 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75  ite3_int64) valu
15e30 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74  es.** that are t
15e40 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20  he default mmap 
15e50 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20  size limit (the 
15e60 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15e70 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d  for.** [PRAGMA m
15e80 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74  map_size]) and t
15e90 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
15ea0 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  ed mmap size lim
15eb0 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  it..** ^The defa
15ec0 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20  ult setting can 
15ed0 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  be overridden by
15ee0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
15ef0 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a  onnection using.
15f00 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50  ** either the [P
15f10 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
15f20 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20   command, or by 
15f30 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
15f40 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
15f50 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
15f60 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d  ol.  ^(The maxim
15f70 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
15f80 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  size.** will be 
15f90 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
15fa0 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 20  ed if necessary 
15fb0 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  so that it does 
15fc0 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a  not exceed the.*
15fd0 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  * compile-time m
15fe0 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65  aximum mmap size
15ff0 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
16000 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f  SQLITE_MAX_MMAP_
16010 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SIZE] compile-ti
16020 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  me option.)^.** 
16030 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d  ^If either argum
16040 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69  ent to this opti
16050 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  on is negative, 
16060 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65  then that argume
16070 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64  nt is.** changed
16080 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d   to its compile-
16090 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  time default..**
160a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
160b0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
160c0 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
160d0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
160e0 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  HEAPSIZE.** <dd>
160f0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
16100 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
16110 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  E option is only
16120 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
16130 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
16140 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20  led for Windows 
16150 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
16160 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70  _WIN32_MALLOC] p
16170 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
16180 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e  ro.** defined. ^
16190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
161a0 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b  N32_HEAPSIZE tak
161b0 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69  es a 32-bit unsi
161c0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c  gned integer val
161d0 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69  ue.** that speci
161e0 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  fies the maximum
161f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65   size of the cre
16200 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a  ated heap..**.**
16210 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16220 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a  _PCACHE_HDRSZ]].
16230 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16240 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16250 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
16260 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16270 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20  HE_HDRSZ option 
16280 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
16290 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
162a0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
162b0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
162c0 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61   writes into tha
162d0 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75  t integer the nu
162e0 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a  mber of extra.**
162f0 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20   bytes per page 
16300 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63  required for eac
16310 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54  h page in [SQLIT
16320 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
16330 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75  HE]..** The amou
16340 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63  nt of extra spac
16350 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63  e required can c
16360 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20  hange depending 
16370 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c  on the compiler,
16380 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66  .** target platf
16390 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20  orm, and SQLite 
163a0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  version..**.** [
163b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
163c0 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  MASZ]].** <dt>SQ
163d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
163e0 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
163f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
16400 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
16410 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
16420 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e  r which.** is an
16430 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
16440 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22  r and sets the "
16450 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  Minimum PMA Size
16460 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74  " for the multit
16470 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65  hreaded.** sorte
16480 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  r to that intege
16490 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  r.  The default 
164a0 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  minimum PMA Size
164b0 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a   is set by the.*
164c0 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52  * [SQLITE_SORTER
164d0 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d  _PMASZ] compile-
164e0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65  time option.  Ne
164f0 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61  w threads are la
16500 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c  unched.** to hel
16510 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72  p with sort oper
16520 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74  ations when mult
16530 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e  ithreaded sortin
16540 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20  g.** is enabled 
16550 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47  (using the [PRAG
16560 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d  MA threads] comm
16570 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f  and) and the amo
16580 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a  unt of content.*
16590 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65  * to be sorted e
165a0 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20  xceeds the page 
165b0 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d  size times the m
165c0 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a  inimum of the.**
165d0 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73   [PRAGMA cache_s
165e0 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64  ize] setting and
165f0 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a   this value..**.
16600 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16610 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
16620 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  L]].** <dt>SQLIT
16630 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
16640 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e  L_SPILL.** <dd>^
16650 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16660 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
16670 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
16680 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
16690 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65   which.** become
166a0 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74  s the [statement
166b0 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d   journal] spill-
166c0 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c  to-disk threshol
166d0 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65  d.  .** [Stateme
166e0 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65  nt journals] are
166f0 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20   held in memory 
16700 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65  until their size
16710 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65   (in bytes).** e
16720 78 63 65 65 64 73 20 74 68 69 73 20 74 68 72 65  xceeds this thre
16730 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20  shold, at which 
16740 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20 77  point they are w
16750 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a  ritten to disk..
16760 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68 72  ** Or if the thr
16770 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74  eshold is -1, st
16780 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73  atement journals
16790 20 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64   are always held
167a0 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20  .** exclusively 
167b0 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69  in memory..** Si
167c0 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65  nce many stateme
167d0 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65  nt journals neve
167e0 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20  r become large, 
167f0 73 65 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c  setting the spil
16800 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74  l.** threshold t
16810 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68 20 61  o a value such a
16820 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61  s 64KiB can grea
16830 74 6c 79 20 72 65 64 75 63 65 20 74 68 65 20 61  tly reduce the a
16840 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20  mount of.** I/O 
16850 72 65 71 75 69 72 65 64 20 74 6f 20 73 75 70 70  required to supp
16860 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f  ort statement ro
16870 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64  llback..** The d
16880 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
16890 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73   this setting is
168a0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74   controlled by t
168b0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54  he.** [SQLITE_ST
168c0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f  MTJRNL_SPILL] co
168d0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
168e0 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  n..** </dl>.*/.#
168f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16900 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
16910 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
16920 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16930 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
16940 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
16950 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16960 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
16970 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
16980 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16990 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
169a0 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
169b0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
169c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
169d0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
169e0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
169f0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
16a00 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16a10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
16a20 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
16a30 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
16a40 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
16a50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
16a60 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
16a70 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
16a80 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
16a90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16aa0 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
16ab0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
16ac0 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
16ad0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16ae0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
16af0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
16b00 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
16b10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
16b20 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
16b30 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
16b40 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
16b50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16b60 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
16b70 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
16b80 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
16b90 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
16ba0 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
16bb0 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
16bc0 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
16bd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16be0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16bf0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
16c00 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
16c10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16c20 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
16c30 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
16c40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16c50 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
16c60 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
16c70 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16c80 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
16c90 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
16ca0 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
16cb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
16cc0 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
16cd0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16ce0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16cf0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
16d00 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
16d10 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
16d20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16d30 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
16d40 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
16d50 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
16d60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16d70 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
16d80 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
16d90 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
16da0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16db0 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
16dc0 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
16dd0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
16de0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
16df0 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
16e00 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
16e10 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
16e20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16e30 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
16e40 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f  PSIZE      23  /
16e50 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
16e60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16e70 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16e80 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20  Z        24  /* 
16e90 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66  int *psz */.#def
16ea0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16eb0 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20  G_PMASZ         
16ec0 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73        25  /* uns
16ed0 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20  igned int szPma 
16ee0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16ef0 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
16f00 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20  L_SPILL      26 
16f10 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
16f20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16f30 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
16f40 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
16f50 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
16f60 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
16f70 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
16f80 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
16f90 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16fa0 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
16fb0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
16fc0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
16fd0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
16fe0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
16ff0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
17000 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17010 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
17020 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
17030 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
17040 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
17050 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
17060 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
17070 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
17080 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
17090 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
170a0 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
170b0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
170c0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
170d0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
170e0 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
170f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17100 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
17110 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
17120 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
17130 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
17140 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
17150 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
17160 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
17170 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
17180 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
17190 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
171a0 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
171b0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
171c0 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
171d0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
171e0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
171f0 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
17200 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
17210 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
17220 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
17230 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17240 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
17250 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
17260 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
17270 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
17280 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
17290 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
172a0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
172b0 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
172c0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
172d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
172e0 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
172f0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
17300 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
17310 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
17320 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
17330 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
17340 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
17350 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
17360 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
17370 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
17380 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
17390 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
173a0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
173b0 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
173c0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
173d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
173e0 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
173f0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
17400 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
17410 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
17420 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
17430 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
17440 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
17450 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
17460 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
17470 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
17480 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
17490 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
174a0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
174b0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
174c0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
174d0 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
174e0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
174f0 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
17500 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
17510 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
17520 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
17530 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
17540 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
17550 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
17560 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
17570 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
17580 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
17590 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
175a0 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
175b0 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
175c0 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
175d0 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
175e0 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
175f0 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
17600 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
17610 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
17620 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
17630 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
17640 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
17650 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
17660 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
17670 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
17680 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
17690 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
176a0 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
176b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
176c0 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
176d0 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
176e0 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
176f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
17700 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
17710 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
17720 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
17730 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
17740 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
17750 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
17760 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
17770 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
17780 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
17790 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
177a0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
177b0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
177c0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
177d0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
177e0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
177f0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
17800 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
17810 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
17820 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
17830 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
17840 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
17850 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
17860 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17870 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
17880 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
17890 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
178a0 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
178b0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
178c0 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
178d0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
178e0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
178f0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
17900 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
17910 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
17920 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
17930 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
17940 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
17950 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17960 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17970 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
17980 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
17990 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
179a0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
179b0 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
179c0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
179d0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
179e0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
179f0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17a00 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17a10 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17a20 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
17a30 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
17a40 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
17a50 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
17a60 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
17a70 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
17a80 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
17a90 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
17aa0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17ab0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17ac0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
17ad0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
17ae0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
17af0 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
17b00 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
17b10 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
17b20 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
17b30 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17b40 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
17b50 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
17b60 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
17b70 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
17b80 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
17b90 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
17ba0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
17bb0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54  CONFIG_ENABLE_FT
17bc0 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74  S3_TOKENIZER</dt
17bd0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17be0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17bf0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
17c00 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75  ble the two-argu
17c10 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20  ment.** version 
17c20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b  of the [fts3_tok
17c30 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69  enizer()] functi
17c40 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61 72 74  on which is part
17c50 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33   of the.** [FTS3
17c60 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72  ] full-text sear
17c70 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73  ch engine extens
17c80 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  ion..** There sh
17c90 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
17ca0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17cb0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
17cc0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
17cd0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
17ce0 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33   to disable fts3
17cf0 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a  _tokenizer() or.
17d00 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
17d10 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  nable fts3_token
17d20 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69  izer() or negati
17d30 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
17d40 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61  setting.** uncha
17d50 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
17d60 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
17d70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17d80 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
17d90 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
17da0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
17db0 63 61 74 65 20 77 68 65 74 68 65 72 20 66 74 73  cate whether fts
17dc0 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64  3_tokenizer is d
17dd0 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
17de0 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
17df0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17e00 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17e10 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
17e20 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
17e30 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77  ich case the new
17e40 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
17e50 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
17e60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
17e70 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
17e80 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
17e90 41 53 49 44 45 20 20 20 20 20 20 20 20 20 20 20  ASIDE           
17ea0 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20    1001 /* void* 
17eb0 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
17ec0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
17ed0 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20  IG_ENABLE_FKEY  
17ee0 20 20 20 20 20 20 20 20 20 31 30 30 32 20 2f 2a           1002 /*
17ef0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
17f00 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
17f10 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
17f20 47 45 52 20 20 20 20 20 20 20 20 31 30 30 33 20  GER        1003 
17f30 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
17f40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
17f50 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54  CONFIG_ENABLE_FT
17f60 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30  S3_TOKENIZER 100
17f70 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  4 /* int int* */
17f80 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
17f90 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
17fa0 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
17fb0 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45  sult Codes.** ME
17fc0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
17fd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
17fe0 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
17ff0 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65  _codes() routine
18000 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
18010 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74  bles the.** [ext
18020 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
18030 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53  es] feature of S
18040 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65  QLite. ^The exte
18050 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
18060 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65  odes are disable
18070 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
18080 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70   historical comp
18090 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51  atibility..*/.SQ
180a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
180b0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
180c0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
180d0 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
180e0 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
180f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18100 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
18110 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  id.** METHOD: sq
18120 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  lite3.**.** ^Eac
18130 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20  h entry in most 
18140 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65  SQLite tables (e
18150 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f  xcept for [WITHO
18160 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
18170 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75  ).** has a uniqu
18180 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
18190 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
181a0 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
181b0 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
181c0 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
181d0 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
181e0 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
181f0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
18200 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
18210 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
18220 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
18230 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
18240 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
18250 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
18260 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
18270 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
18280 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
18290 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
182a0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
182b0 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
182c0 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
182d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
182e0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
182f0 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63  owid(D) interfac
18300 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
18310 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a  owid] of the .**
18320 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
18330 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
18340 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61   into a rowid ta
18350 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ble or [virtual 
18360 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74  table].** on dat
18370 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18380 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20   D..** ^Inserts 
18390 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f  into [WITHOUT RO
183a0 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20  WID] tables are 
183b0 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a  not recorded..**
183c0 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
183d0 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74  ul [INSERT]s int
183e0 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a  o rowid tables.*
183f0 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
18400 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61  rred on the data
18410 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18420 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  D, .** then sqli
18430 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
18440 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
18450 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49   zero..**.** ^(I
18460 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
18470 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
18480 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
18490 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
184a0 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
184b0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
184c0 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
184d0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
184e0 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
184f0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
18500 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
18510 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
18520 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
18530 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
18540 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
18550 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
18560 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
18570 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
18580 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
18590 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
185a0 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
185b0 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
185c0 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
185d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
185e0 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
185f0 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
18600 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
18610 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
18620 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
18630 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
18640 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
18650 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
18660 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
18670 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
18680 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
18690 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
186a0 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
186b0 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
186c0 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
186d0 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
186e0 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
186f0 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
18700 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
18710 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
18720 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
18730 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
18740 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
18750 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
18760 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
18770 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
18780 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
18790 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
187a0 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
187b0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
187c0 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
187d0 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
187e0 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
187f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
18800 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
18810 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
18820 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
18830 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
18840 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
18850 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
18860 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
18870 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
18880 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
18890 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
188a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
188b0 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
188c0 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
188d0 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
188e0 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
188f0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
18900 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
18910 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
18920 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
18930 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
18940 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
18950 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
18960 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
18970 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
18980 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
18990 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
189a0 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
189b0 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
189c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
189d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
189e0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
189f0 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
18a00 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
18a10 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
18a20 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
18a30 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
18a40 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
18a50 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
18a60 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f  e3_int64 SQLITE_
18a70 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
18a80 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
18a90 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
18aa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
18ab0 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
18ac0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
18ad0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
18ae0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
18af0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
18b00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
18b10 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73  ws modified, ins
18b20 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  erted or.** dele
18b30 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
18b40 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
18b50 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
18b60 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  E or DELETE.** s
18b70 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20  tatement on the 
18b80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18b90 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79  ion specified by
18ba0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
18bb0 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69  ter..** ^Executi
18bc0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
18bd0 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
18be0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69  nt does not modi
18bf0 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  fy the value.** 
18c00 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
18c10 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
18c20 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d   ^Only changes m
18c30 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20  ade directly by 
18c40 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41  the INSERT, UPDA
18c50 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
18c60 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f  tement are.** co
18c70 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c  nsidered - auxil
18c80 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
18c90 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54  sed by [CREATE T
18ca0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
18cb0 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  s], .** [foreign
18cc0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72   key actions] or
18cd0 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
18ce0 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
18cf0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
18d00 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73  ..** .** Changes
18d10 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
18d20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20  are intercepted 
18d30 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20  by .** [INSTEAD 
18d40 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53  OF trigger | INS
18d50 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73  TEAD OF triggers
18d60 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
18d70 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a  d. ^The value .*
18d80 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
18d90 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
18da0 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65  immediately afte
18db0 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  r an INSERT, UPD
18dc0 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54  ATE or .** DELET
18dd0 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20  E statement run 
18de0 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77  on a view is alw
18df0 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63  ays zero. Only c
18e00 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72  hanges made to r
18e10 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61  eal .** tables a
18e20 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
18e30 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72  * Things are mor
18e40 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66  e complicated if
18e50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
18e60 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
18e70 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77  is.** executed w
18e80 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70  hile a trigger p
18e90 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e  rogram is runnin
18ea0 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70  g. This may happ
18eb0 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f  en if the.** pro
18ec0 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63  gram uses the [c
18ed0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
18ee0 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f  ction], or if so
18ef0 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63  me other callbac
18f00 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e  k.** function in
18f10 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68  vokes sqlite3_ch
18f20 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79  anges() directly
18f30 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a  . Essentially:.*
18f40 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  * .** <ul>.**   
18f50 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e  <li> ^(Before en
18f60 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72  tering a trigger
18f70 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c   program the val
18f80 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ue returned by.*
18f90 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33  *        sqlite3
18fa0 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
18fb0 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66  ion is saved. Af
18fc0 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20  ter the trigger 
18fd0 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20  program .**     
18fe0 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c     has finished,
18ff0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61   the original va
19000 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e  lue is restored.
19010 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e  )^.** .**   <li>
19020 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67   ^(Within a trig
19030 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68  ger program each
19040 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
19050 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20  and DELETE .**  
19060 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20        statement 
19070 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72  sets the value r
19080 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
19090 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
190a0 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d          upon com
190b0 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61  pletion as norma
190c0 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68  l. Of course, th
190d0 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f  is value will no
190e0 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20  t include .**   
190f0 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73       any changes
19100 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75   performed by su
19110 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74  b-triggers, as t
19120 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
19130 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
19140 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61  value will be sa
19150 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64  ved and restored
19160 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d   after each sub-
19170 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e  trigger has run.
19180 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a  )^.** </ul>.** .
19190 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74  ** ^This means t
191a0 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67  hat if the chang
191b0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
191c0 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69  n (or similar) i
191d0 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65  s used.** by the
191e0 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55   first INSERT, U
191f0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
19200 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
19210 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a   a trigger, it .
19220 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  ** returns the v
19230 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e  alue as set when
19240 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61   the calling sta
19250 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65  tement began exe
19260 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69  cuting..** ^If i
19270 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  t is used by the
19280 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65   second or subse
19290 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65  quent such state
192a0 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72  ment within a tr
192b0 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61  igger .** progra
192c0 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  m, the value ret
192d0 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74  urned reflects t
192e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
192f0 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68  s modified by th
19300 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49  e .** previous I
19310 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
19320 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
19330 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
19340 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a  e trigger..**.**
19350 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
19360 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
19370 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
19380 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
19390 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
193a0 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
193b0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
193c0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
193d0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
193e0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
193f0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
19400 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
19410 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
19420 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
19430 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
19440 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
19450 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
19460 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
19470 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
19480 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
19490 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 68  DCALL sqlite3_ch
194a0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
194b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
194c0 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
194d0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
194e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
194f0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
19500 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
19510 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
19520 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65   of rows inserte
19530 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a  d, modified or.*
19540 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c  * deleted by all
19550 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
19560 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
19570 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c  statements compl
19580 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68  eted.** since th
19590 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
195a0 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64  ction was opened
195b0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73  , including thos
195c0 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a  e executed as.**
195d0 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72   part of trigger
195e0 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63   programs. ^Exec
195f0 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
19600 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
19610 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f  ement.** does no
19620 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c  t affect the val
19630 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
19640 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
19650 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e  nges()..** .** ^
19660 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20  Changes made as 
19670 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e  part of [foreign
19680 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
19690 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  e included in th
196a0 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20  e.** count, but 
196b0 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61  those made as pa
196c0 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  rt of REPLACE co
196d0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
196e0 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20  ion are.** not. 
196f0 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
19700 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
19710 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45  rcepted by INSTE
19720 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a  AD OF triggers .
19730 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
19740 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61  ed..** .** See a
19750 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
19760 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
19770 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
19780 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
19790 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
197a0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
197b0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
197c0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
197d0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
197e0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
197f0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
19800 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
19810 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
19820 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
19830 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
19840 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
19850 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
19860 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
19870 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
19880 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
19890 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 6f  DCALL sqlite3_to
198a0 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
198b0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
198c0 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
198d0 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
198e0 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44   Query.** METHOD
198f0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
19900 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
19910 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
19920 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
19930 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
19940 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
19950 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
19960 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
19970 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
19980 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
19990 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
199a0 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
199b0 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
199c0 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
199d0 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
199e0 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
199f0 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
19a00 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
19a10 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
19a20 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
19a30 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
19a40 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
19a50 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
19a60 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
19a70 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
19a80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
19a90 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
19aa0 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
19ab0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
19ac0 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
19ad0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19ae0 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
19af0 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
19b00 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
19b10 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
19b20 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
19b30 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
19b40 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
19b50 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
19b60 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
19b70 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
19b80 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
19b90 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
19ba0 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
19bb0 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
19bc0 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
19bd0 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
19be0 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
19bf0 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
19c00 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
19c10 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
19c20 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
19c30 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
19c40 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
19c50 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
19c60 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
19c70 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
19c80 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
19c90 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
19ca0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
19cb0 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
19cc0 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
19cd0 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
19ce0 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
19cf0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
19d00 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
19d10 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
19d20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
19d30 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
19d40 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
19d50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19d60 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
19d70 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
19d80 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
19d90 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
19da0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
19db0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
19dc0 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
19dd0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
19de0 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
19df0 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
19e00 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
19e10 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
19e20 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
19e30 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
19e40 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
19e50 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
19e60 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
19e70 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
19e80 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
19e90 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
19ea0 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
19eb0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
19ec0 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
19ed0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
19ee0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
19ef0 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
19f00 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
19f10 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
19f20 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
19f30 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
19f40 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
19f50 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
19f60 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
19f70 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
19f80 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
19f90 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
19fa0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
19fb0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
19fc0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
19fd0 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
19fe0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
19ff0 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
1a000 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
1a010 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1a020 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1a030 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1a040 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
1a050 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1a060 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
1a070 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
1a080 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
1a090 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1a0a0 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
1a0b0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
1a0c0 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
1a0d0 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
1a0e0 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
1a0f0 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
1a100 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
1a110 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
1a120 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
1a130 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
1a140 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
1a150 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
1a160 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
1a170 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1a180 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
1a190 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
1a1a0 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
1a1b0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
1a1c0 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
1a1d0 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
1a1e0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
1a1f0 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
1a200 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
1a210 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
1a220 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
1a230 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
1a240 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
1a250 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
1a260 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
1a270 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
1a280 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
1a290 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
1a2a0 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
1a2b0 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
1a2c0 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
1a2d0 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
1a2e0 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
1a2f0 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
1a300 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
1a310 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
1a320 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
1a330 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
1a340 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
1a350 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
1a360 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
1a370 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
1a380 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
1a390 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1a3a0 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
1a3b0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
1a3c0 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
1a3d0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
1a3e0 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
1a3f0 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
1a400 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1a410 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1a420 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
1a430 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1a440 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
1a450 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
1a460 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
1a470 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
1a480 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
1a490 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
1a4a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1a4b0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
1a4c0 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
1a4d0 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
1a4e0 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
1a4f0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
1a500 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
1a510 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
1a520 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
1a530 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
1a540 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
1a550 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
1a560 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1a570 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
1a580 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
1a590 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
1a5a0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1a5b0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
1a5c0 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
1a5d0 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
1a5e0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
1a5f0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
1a600 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1a610 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1a620 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
1a630 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1a640 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1a650 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
1a660 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1a670 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
1a680 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
1a690 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  rder..*/.SQLITE_
1a6a0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
1a6b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
1a6c0 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
1a6d0 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45  ar *sql);.SQLITE
1a6e0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
1a6f0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1a700 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
1a710 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
1a720 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1a730 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
1a740 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
1a750 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
1a760 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
1a770 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
1a780 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
1a790 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
1a7a0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1a7b0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1a7c0 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
1a7d0 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
1a7e0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
1a7f0 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
1a800 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
1a810 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
1a820 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
1a830 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1a840 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
1a850 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
1a860 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
1a870 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
1a880 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
1a890 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
1a8a0 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
1a8b0 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
1a8c0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a8d0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
1a8e0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1a8f0 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
1a900 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
1a910 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
1a920 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
1a930 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1a940 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
1a950 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
1a960 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1a970 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
1a980 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
1a990 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
1a9a0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
1a9b0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
1a9c0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1a9d0 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
1a9e0 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
1a9f0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1aa00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1aa10 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
1aa20 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
1aa30 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
1aa40 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
1aa50 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1aa60 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
1aa70 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
1aa80 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1aa90 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
1aaa0 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
1aab0 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
1aac0 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
1aad0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1aae0 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
1aaf0 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
1ab00 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
1ab10 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
1ab20 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
1ab30 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
1ab40 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
1ab50 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
1ab60 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
1ab70 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1ab80 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
1ab90 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
1aba0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1abb0 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
1abc0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1abd0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1abe0 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1abf0 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
1ac00 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1ac10 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
1ac20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1ac30 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1ac40 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1ac50 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1ac60 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1ac70 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1ac80 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1ac90 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1aca0 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1acb0 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1acc0 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1acd0 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1ace0 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1acf0 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1ad00 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1ad10 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
1ad20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1ad30 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
1ad40 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
1ad50 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1ad60 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1ad70 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1ad80 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1ad90 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1ada0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1adb0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1adc0 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1add0 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1ade0 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1adf0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1ae00 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1ae10 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1ae20 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1ae30 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1ae40 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1ae50 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1ae60 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1ae70 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1ae80 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1ae90 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1aea0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1aeb0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1aec0 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1aed0 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1aee0 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1aef0 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1af00 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1af10 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1af20 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1af30 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1af40 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1af50 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1af60 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1af70 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1af80 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1af90 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1afa0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1afb0 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1afc0 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1afd0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1afe0 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1aff0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1b000 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1b010 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1b020 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1b030 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1b040 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1b050 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1b060 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1b070 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1b080 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1b090 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1b0a0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1b0b0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1b0c0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1b0d0 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1b0e0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1b0f0 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1b100 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1b110 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1b120 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1b130 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1b140 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1b150 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1b160 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1b170 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1b180 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1b190 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b1a0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1b1b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1b1c0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1b1d0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1b1e0 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1b1f0 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1b200 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1b210 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1b220 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1b230 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1b240 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1b250 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b260 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1b270 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1b280 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1b290 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1b2a0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1b2b0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
1b2c0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1b2d0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
1b2e0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
1b2f0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1b300 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
1b310 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
1b320 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1b330 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  3.**.** ^This ro
1b340 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
1b350 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1b360 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
1b370 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
1b380 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
1b390 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
1b3a0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
1b3b0 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
1b3c0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
1b3d0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
1b3e0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
1b3f0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1b400 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1b410 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
1b420 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
1b430 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1b440 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1b450 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
1b460 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
1b470 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
1b480 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
1b490 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
1b4a0 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  E_BUSY]..**.** ^
1b4b0 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
1b4c0 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
1b4d0 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
1b4e0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
1b4f0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
1b500 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
1b510 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1b520 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1b530 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1b540 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
1b550 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1b560 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e  onnection] at an
1b570 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
1b580 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
1b590 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
1b5a0 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
1b5b0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1b5c0 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
1b5d0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
1b5e0 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
1b5f0 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
1b600 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
1b610 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
1b620 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  :  [PRAGMA busy_
1b630 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49  timeout].*/.SQLI
1b640 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
1b650 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1b660 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
1b670 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
1b680 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b690 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
1b6a0 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
1b6b0 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d  ing Queries.** M
1b6c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1b6d0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
1b6e0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
1b6f0 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
1b700 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
1b710 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1b720 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
1b730 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
1b740 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
1b750 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
1b760 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
1b770 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
1b780 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
1b790 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
1b7a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1b7b0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
1b7c0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1b7d0 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
1b7e0 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
1b7f0 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
1b800 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
1b810 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1b820 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1b830 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1b840 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1b850 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1b860 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1b870 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1b880 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1b890 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1b8a0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1b8b0 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1b8c0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1b8d0 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1b8e0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1b8f0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1b900 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1b910 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1b920 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1b930 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1b940 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1b950 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1b960 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1b970 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1b980 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1b990 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1b9a0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1b9b0 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1b9c0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1b9d0 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1b9e0 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1b9f0 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1ba00 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1ba10 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1ba20 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1ba30 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1ba40 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1ba50 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1ba60 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1ba70 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1ba80 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1ba90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1baa0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1bab0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1bac0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1bad0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1bae0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1baf0 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1bb00 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1bb10 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1bb20 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1bb30 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1bb40 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1bb50 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1bb60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1bb70 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1bb80 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1bb90 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1bba0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1bbb0 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1bbc0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1bbd0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1bbe0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1bbf0 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1bc00 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1bc10 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1bc20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1bc30 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1bc40 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1bc50 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1bc60 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1bc70 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1bc80 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1bc90 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1bca0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1bcb0 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1bcc0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1bcd0 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1bce0 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1bcf0 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1bd00 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1bd10 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1bd20 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1bd30 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1bd40 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1bd50 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1bd60 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1bd70 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1bd80 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1bd90 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1bda0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1bdb0 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1bdc0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1bdd0 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1bde0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1bdf0 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1be00 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1be10 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1be20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1be30 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1be40 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1be50 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1be60 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1be70 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1be80 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1be90 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1bea0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1beb0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1bec0 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1bed0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1bee0 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1bef0 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1bf00 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1bf10 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1bf20 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1bf30 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1bf40 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1bf50 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1bf60 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1bf70 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1bf80 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1bf90 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1bfa0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1bfb0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1bfc0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1bfd0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1bfe0 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1bff0 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1c000 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1c010 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1c020 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1c030 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1c040 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1c050 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1c060 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1c070 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1c080 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1c090 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1c0a0 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1c0b0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1c0c0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1c0d0 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1c0e0 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1c0f0 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1c100 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1c110 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1c120 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1c130 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1c140 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1c150 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1c160 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1c170 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1c180 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1c190 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1c1a0 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1c1b0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1c1c0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1c1d0 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1c1e0 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1c1f0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1c200 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1c210 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1c220 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1c230 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1c240 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1c250 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1c260 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1c270 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1c280 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1c290 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1c2a0 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1c2b0 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1c2c0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1c2d0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1c2e0 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1c2f0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1c300 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1c310 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
1c320 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 65  DCALL sqlite3_ge
1c330 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
1c340 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1c350 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
1c360 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
1c370 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1c380 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
1c390 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
1c3a0 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
1c3b0 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
1c3c0 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
1c3d0 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
1c3e0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1c3f0 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
1c400 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1c410 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
1c420 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1c430 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
1c440 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1c450 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
1c460 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
1c470 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
1c480 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  ere */.);.SQLITE
1c490 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
1c4a0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1c4b0 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
1c4c0 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
1c4d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
1c4e0 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
1c4f0 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
1c500 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1c510 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
1c520 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
1c530 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
1c540 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
1c550 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
1c560 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54   C library..** T
1c570 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e  hese routines un
1c580 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66  derstand most of
1c590 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20   the common K&R 
1c5a0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1c5b0 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65  ns,.** plus some
1c5c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d   additional non-
1c5d0 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73  standard formats
1c5e0 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77  , detailed below
1c5f0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73  ..** Note that s
1c600 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20  ome of the more 
1c610 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69  obscure formatti
1c620 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20  ng options from 
1c630 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72  recent.** C-libr
1c640 61 72 79 20 73 74 61 6e 64 61 72 64 73 20 61 72  ary standards ar
1c650 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  e omitted from t
1c660 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  his implementati
1c670 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
1c680 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1c690 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
1c6a0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
1c6b0 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
1c6c0 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
1c6d0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
1c6e0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
1c6f0 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
1c700 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1c710 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
1c720 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
1c730 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
1c740 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
1c750 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
1c760 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
1c770 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
1c780 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
1c790 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1c7a0 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
1c7b0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1c7c0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
1c7d0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
1c7e0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1c7f0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
1c800 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
1c810 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
1c820 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1c830 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
1c840 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
1c850 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
1c860 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
1c870 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1c880 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
1c890 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
1c8a0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
1c8b0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
1c8c0 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
1c8d0 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
1c8e0 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
1c8f0 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
1c900 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
1c910 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
1c920 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
1c930 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
1c940 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
1c950 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1c960 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
1c970 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
1c980 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
1c990 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1c9a0 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
1c9b0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
1c9c0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
1c9d0 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
1c9e0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
1c9f0 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
1ca00 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
1ca10 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1ca20 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
1ca30 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
1ca40 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
1ca50 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
1ca60 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
1ca70 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
1ca80 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1ca90 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
1caa0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
1cab0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
1cac0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
1cad0 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
1cae0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
1caf0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1cb00 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
1cb10 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
1cb20 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
1cb30 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
1cb40 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1cb50 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
1cb60 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
1cb70 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
1cb80 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
1cb90 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
1cba0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
1cbb0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
1cbc0 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
1cbd0 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
1cbe0 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
1cbf0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
1cc00 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
1cc10 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1cc20 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
1cc30 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1cc40 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
1cc50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1cc60 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
1cc70 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
1cc80 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
1cc90 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
1cca0 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
1ccb0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
1ccc0 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
1ccd0 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
1cce0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1ccf0 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
1cd00 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
1cd10 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
1cd20 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25  %Q", "%w" and "%
1cd30 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  z" options..**.*
1cd40 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f  * ^(The %q optio
1cd50 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
1cd60 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
1cd70 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72  itutes a nul-ter
1cd80 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1cd90 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
1cda0 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
1cdb0 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
1cdc0 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
1cdd0 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
1cde0 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
1cdf0 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
1ce00 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f  iteral.)^  By do
1ce10 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
1ce20 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
1ce30 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
1ce40 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
1ce50 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
1ce60 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
1ce70 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
1ce80 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
1ce90 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
1cea0 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
1ceb0 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
1cec0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1ced0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1cee0 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
1cef0 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
1cf00 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
1cf10 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1cf20 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
1cf30 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
1cf40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
1cf50 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1cf60 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1cf70 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1cf80 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1cf90 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1cfa0 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
1cfb0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1cfc0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1cfd0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1cfe0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1cff0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1d000 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1d010 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
1d020 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
1d030 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
1d040 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
1d050 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
1d060 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
1d070 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
1d080 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1d090 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1d0a0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1d0b0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1d0c0 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
1d0d0 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
1d0e0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1d0f0 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
1d100 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
1d110 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
1d120 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
1d130 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
1d140 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
1d150 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
1d160 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1d170 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1d180 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1d190 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1d1a0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1d1b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1d1c0 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
1d1d0 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
1d1e0 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
1d1f0 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
1d200 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
1d210 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
1d220 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
1d230 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
1d240 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1d250 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  l..**.** ^(The %
1d260 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
1d270 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
1d280 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
1d290 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
1d2a0 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
1d2b0 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
1d2c0 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
1d2d0 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
1d2e0 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
1d2f0 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
1d300 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
1d310 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
1d320 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
1d330 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
1d340 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c   quotes).)^  So,
1d350 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
1d360 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
1d370 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1d380 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1d390 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1d3a0 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1d3b0 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1d3c0 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
1d3d0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1d3e0 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1d3f0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1d400 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1d410 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1d420 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
1d430 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
1d440 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
1d450 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
1d460 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
1d470 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
1d480 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
1d490 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1d4a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77  .**.** ^(The "%w
1d4b0 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1d4c0 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22  ion is like "%q"
1d4d0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1d4e0 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65  expects to.** be
1d4f0 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69   contained withi
1d500 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20  n double-quotes 
1d510 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c  instead of singl
1d520 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74  e quotes, and it
1d530 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65 20  .** escapes the 
1d540 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61  double-quote cha
1d550 72 61 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f  racter instead o
1d560 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f  f the single-quo
1d570 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e  te.** character.
1d580 29 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f 72  )^  The "%w" for
1d590 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1d5a0 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73  s intended for s
1d5b0 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a  afely inserting.
1d5c0 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  ** table and col
1d5d0 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61  umn names into a
1d5e0 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c   constructed SQL
1d5f0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
1d600 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
1d610 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
1d620 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
1d630 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
1d640 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
1d650 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
1d660 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
1d670 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
1d680 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
1d690 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
1d6a0 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
1d6b0 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
1d6c0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1d6d0 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71  *SQLITE_CDECL sq
1d6e0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
1d6f0 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
1d700 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1d710 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
1d720 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1d730 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
1d740 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41  _list);.SQLITE_A
1d750 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  PI char *SQLITE_
1d760 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 73 6e  CDECL sqlite3_sn
1d770 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1d780 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
1d790 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .);.SQLITE_API c
1d7a0 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
1d7b0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  ALL sqlite3_vsnp
1d7c0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1d7d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1d7e0 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
1d7f0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1d800 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
1d810 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
1d820 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
1d830 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
1d840 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
1d850 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
1d860 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
1d870 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
1d880 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
1d890 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
1d8a0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1d8b0 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
1d8c0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
1d8d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1d8e0 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
1d8f0 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
1d900 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1d910 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
1d920 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
1d930 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1d940 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1d950 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1d960 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
1d970 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
1d980 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
1d990 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1d9a0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
1d9b0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1d9c0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
1d9d0 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
1d9e0 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
1d9f0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
1da00 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
1da10 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1da20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
1da30 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
1da40 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
1da50 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
1da60 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
1da70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1da80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1da90 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75  _malloc64(N) rou
1daa0 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20  tine works just 
1dab0 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  like.** sqlite3_
1dac0 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74  malloc(N) except
1dad0 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e   that N is an un
1dae0 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e  signed 64-bit in
1daf0 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1db00 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d   of a signed 32-
1db10 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  bit integer..**.
1db20 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
1db30 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
1db40 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
1db50 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
1db60 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1db70 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1db80 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
1db90 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
1dba0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
1dbb0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
1dbc0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
1dbd0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
1dbe0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
1dbf0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1dc00 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
1dc10 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
1dc20 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
1dc30 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
1dc40 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
1dc50 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
1dc60 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
1dc70 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
1dc80 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
1dc90 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
1dca0 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
1dcb0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
1dcc0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1dcd0 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
1dce0 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
1dcf0 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
1dd00 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
1dd10 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
1dd20 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
1dd30 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
1dd40 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1dd50 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1dd60 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1dd70 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
1dd80 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1dd90 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1dda0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1ddb0 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  loc()..**.** ^Th
1ddc0 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1ddd0 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  c(X,N) interface
1dde0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
1ddf0 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
1de00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1de10 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73   X to be at leas
1de20 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49  t N bytes..** ^I
1de30 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  f the X paramete
1de40 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1de50 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20  lloc(X,N).** is 
1de60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1de70 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1de80 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1de90 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1dea0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a  te3_malloc(N)..*
1deb0 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61  * ^If the N para
1dec0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1ded0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73  _realloc(X,N) is
1dee0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1def0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1df00 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1df10 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1df20 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1df30 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71  _free(X)..** ^sq
1df40 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1df50 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  N) returns a poi
1df60 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
1df70 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
1df80 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
1df90 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
1dfa0 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
1dfb0 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61  nt memory is ava
1dfc0 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
1dfd0 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
1dfe0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1dff0 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
1e000 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
1e010 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1e020 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
1e030 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
1e040 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
1e050 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1e060 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1e070 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
1e080 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
1e090 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
1e0a0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1e0b0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
1e0c0 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20   N is positive, 
1e0d0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f  then the.** prio
1e0e0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1e0f0 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1e100 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
1e110 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74  alloc64(X,N) int
1e120 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68  erfaces works th
1e130 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
1e140 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1e150 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1e160 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69  is a 64-bit unsi
1e170 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73  gned integer ins
1e180 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d  tead.** of a 32-
1e190 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
1e1a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20  er..**.** ^If X 
1e1b0 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  is a memory allo
1e1c0 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c  cation previousl
1e1d0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1e1e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e1f0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
1e200 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33  loc64(), sqlite3
1e210 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73  _realloc(), or s
1e220 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1e230 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  (), then.** sqli
1e240 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1e250 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
1e260 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c   that memory all
1e270 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73  ocation in bytes
1e280 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
1e290 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1e2a0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67  te3_msize(X) mig
1e2b0 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
1e2c0 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  n the number.** 
1e2d0 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74  of bytes request
1e2e0 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c  ed when X was al
1e2f0 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20  located.  ^If X 
1e300 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1e310 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  r then.** sqlite
1e320 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
1e330 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70  ns zero.  If X p
1e340 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69  oints to somethi
1e350 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a  ng that is not.*
1e360 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  * the beginning 
1e370 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
1e380 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70  tion, or if it p
1e390 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65  oints to a forme
1e3a0 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d  rly.** valid mem
1e3b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1e3c0 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e  hat has now been
1e3d0 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65   freed, then the
1e3e0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
1e3f0 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1e400 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
1e410 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66  d possibly harmf
1e420 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ul..**.** ^The m
1e430 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1e440 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1e450 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
1e460 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
1e470 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e  3_malloc64(), an
1e480 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1e490 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  c64().** is alwa
1e4a0 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
1e4b0 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
1e4c0 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
1e4d0 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
1e4e0 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
1e4f0 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
1e500 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
1e510 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
1e520 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
1e530 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
1e540 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
1e550 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
1e560 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
1e570 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
1e580 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
1e590 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
1e5a0 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
1e5b0 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
1e5c0 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
1e5d0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
1e5e0 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
1e5f0 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
1e600 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
1e610 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
1e620 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
1e630 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
1e640 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1e650 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1e660 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
1e670 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
1e680 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
1e690 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
1e6a0 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
1e6b0 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
1e6c0 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
1e6d0 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
1e6e0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
1e6f0 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
1e700 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
1e710 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
1e720 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
1e730 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
1e740 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
1e750 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
1e760 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
1e770 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
1e780 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
1e790 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1e7a0 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1e7b0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1e7c0 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1e7d0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1e7e0 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1e7f0 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1e800 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1e810 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1e820 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1e830 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1e840 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1e850 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1e860 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1e870 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1e880 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1e890 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1e8a0 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1e8b0 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1e8c0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1e8d0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1e8e0 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1e8f0 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1e900 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1e910 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1e920 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1e930 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1e940 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1e950 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1e960 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1e970 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
1e980 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  LL sqlite3_mallo
1e990 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  c(int);.SQLITE_A
1e9a0 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  PI void *SQLITE_
1e9b0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1e9c0 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33  malloc64(sqlite3
1e9d0 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  _uint64);.SQLITE
1e9e0 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54  _API void *SQLIT
1e9f0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1ea00 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
1ea10 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
1ea20 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  I void *SQLITE_S
1ea30 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72  TDCALL sqlite3_r
1ea40 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20  ealloc64(void*, 
1ea50 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
1ea60 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1ea70 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1ea80 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
1ea90 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  d*);.SQLITE_API 
1eaa0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 53  sqlite3_uint64 S
1eab0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1eac0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64  lite3_msize(void
1ead0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1eae0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1eaf0 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
1eb00 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
1eb10 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
1eb20 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
1eb30 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
1eb40 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
1eb50 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
1eb60 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
1eb70 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
1eb80 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1eb90 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
1eba0 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
1ebb0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1ebc0 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
1ebd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
1ebe0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1ebf0 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
1ec00 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1ec10 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
1ec20 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
1ec30 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
1ec40 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
1ec50 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
1ec60 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1ec70 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
1ec80 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
1ec90 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
1eca0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
1ecb0 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
1ecc0 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1ecd0 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
1ece0 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
1ecf0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1ed00 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1ed10 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1ed20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1ed30 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
1ed40 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
1ed50 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
1ed60 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
1ed70 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
1ed80 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1ed90 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
1eda0 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
1edb0 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
1edc0 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
1edd0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
1ede0 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
1edf0 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
1ee00 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1ee10 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1ee20 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
1ee30 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1ee40 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
1ee50 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
1ee60 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
1ee70 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1ee80 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1ee90 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
1eea0 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
1eeb0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
1eec0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1eed0 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
1eee0 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
1eef0 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
1ef00 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
1ef10 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1ef20 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f  e3_int64 SQLITE_
1ef30 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1ef40 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
1ef50 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
1ef60 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49  lite3_int64 SQLI
1ef70 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1ef80 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1ef90 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
1efa0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
1efb0 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
1efc0 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
1efd0 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
1efe0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
1eff0 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
1f000 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
1f010 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
1f020 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
1f030 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
1f040 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
1f050 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
1f060 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
1f070 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
1f080 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
1f090 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
1f0a0 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
1f0b0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
1f0c0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
1f0d0 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
1f0e0 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
1f0f0 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
1f100 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
1f110 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
1f120 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
1f130 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
1f140 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
1f150 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
1f160 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
1f170 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
1f180 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
1f190 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70  r P..** ^The P p
1f1a0 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20  arameter can be 
1f1b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1f1c0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72  **.** ^If this r
1f1d0 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62  outine has not b
1f1e0 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63  een previously c
1f1f0 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20  alled or if the 
1f200 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c  previous.** call
1f210 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e   had N less than
1f220 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70   one or a NULL p
1f230 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68  ointer for P, th
1f240 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a  en the PRNG is.*
1f250 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  * seeded using r
1f260 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
1f270 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ed from the xRan
1f280 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
1f290 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  f.** the default
1f2a0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1f2b0 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  bject..** ^If th
1f2c0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
1f2d0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1f2e0 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72  had an N of 1 or
1f2f0 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e   more and a.** n
1f300 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74  on-NULL P then t
1f310 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
1f320 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
1f330 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
1f340 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
1f350 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
1f360 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
1f370 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
1f380 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1f390 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
1f3a0 4c 4c 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  LL sqlite3_rando
1f3b0 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
1f3c0 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
1f3d0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
1f3e0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
1f3f0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  on Callbacks.** 
1f400 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1f410 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1f420 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1f430 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f440 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1f450 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1f460 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1f470 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1f480 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1f490 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1f4a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1f4b0 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1f4c0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1f4d0 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1f4e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1f4f0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1f500 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1f510 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1f520 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1f530 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1f540 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1f550 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1f560 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1f570 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1f580 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1f590 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1f5a0 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1f5b0 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1f5c0 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1f5d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1f5e0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1f5f0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1f600 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1f610 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1f620 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1f630 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1f640 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1f650 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1f660 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1f670 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1f680 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1f690 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1f6a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1f6b0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1f6c0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1f6d0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1f6e0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1f6f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1f700 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1f710 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1f720 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1f730 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1f740 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1f750 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1f760 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1f770 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1f780 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1f790 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1f7a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1f7b0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1f7c0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1f7d0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1f7e0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1f7f0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1f800 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1f810 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1f820 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1f830 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1f840 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1f850 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1f860 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1f870 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1f880 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1f890 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f8a0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1f8b0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1f8c0 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1f8d0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1f8e0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1f8f0 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1f900 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1f910 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1f920 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1f930 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1f940 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1f950 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1f960 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1f970 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1f980 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1f990 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1f9a0 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1f9b0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1f9c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1f9d0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1f9e0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1f9f0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1fa00 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1fa10 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1fa20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1fa30 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1fa40 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1fa50 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1fa60 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1fa70 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1fa80 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1fa90 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1faa0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1fab0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1fac0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1fad0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1fae0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1faf0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1fb00 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1fb10 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1fb20 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1fb30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fb40 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1fb50 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1fb60 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1fb70 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1fb80 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1fb90 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1fba0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1fbb0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1fbc0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1fbd0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1fbe0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1fbf0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1fc00 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1fc10 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1fc20 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1fc30 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1fc40 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1fc50 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1fc60 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1fc70 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1fc80 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1fc90 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1fca0 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1fcb0 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1fcc0 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1fcd0 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1fce0 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1fcf0 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1fd00 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1fd10 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1fd20 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1fd30 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1fd40 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1fd50 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1fd60 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1fd70 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1fd80 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1fd90 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1fda0 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1fdb0 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1fdc0 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1fdd0 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1fde0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1fdf0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1fe00 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1fe10 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1fe20 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1fe30 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1fe40 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1fe50 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1fe60 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1fe70 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1fe80 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1fe90 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1fea0 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1feb0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1fec0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1fed0 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1fee0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1fef0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1ff00 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1ff10 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1ff20 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1ff30 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1ff40 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1ff50 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1ff60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1ff70 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1ff80 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1ff90 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1ffa0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1ffb0 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1ffc0 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1ffd0 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1ffe0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1fff0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
20000 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
20010 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
20020 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
20030 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
20040 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
20050 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
20060 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
20070 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
20080 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
20090 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
200a0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
200b0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
200c0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
200d0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
200e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
200f0 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
20100 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
20110 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20120 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
20130 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
20140 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
20150 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20160 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
20170 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
20180 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
20190 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
201a0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
201b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
201c0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
201d0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
201e0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
201f0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20200 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
20210 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
20220 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
20230 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
20240 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20250 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
20260 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
20270 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
20280 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
20290 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
202a0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
202b0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
202c0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
202d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
202e0 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
202f0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
20300 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
20310 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
20320 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
20330 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20340 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
20350 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
20360 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
20370 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
20380 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
20390 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
203a0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
203b0 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
203c0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
203d0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
203e0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
203f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20400 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
20410 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
20420 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
20430 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
20440 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
20450 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
20460 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
20470 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
20480 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
20490 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
204a0 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
204b0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
204c0 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
204d0 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
204e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
204f0 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
20500 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
20510 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
20520 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
20530 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
20540 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  ALL sqlite3_set_
20550 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
20560 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
20570 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
20580 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
20590 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
205a0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
205b0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
205c0 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
205d0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
205e0 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
205f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
20600 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
20610 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
20620 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
20630 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
20640 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
20650 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
20660 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
20670 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
20680 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
20690 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
206a0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
206b0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
206c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
206d0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
206e0 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
206f0 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
20700 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
20710 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
20720 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
20730 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
20740 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74  d as a [conflict
20750 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65   resolution mode
20760 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72  ].** returned fr
20770 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
20780 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
20790 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
207a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
207b0 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
207c0 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
207d0 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
207e0 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
207f0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
20800 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
20810 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
20820 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
20830 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
20840 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
20850 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
20860 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
20870 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
20880 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
20890 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
208a0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
208b0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
208c0 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
208d0 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
208e0 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
208f0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
20900 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
20910 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
20920 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
20930 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
20940 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
20950 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
20960 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
20970 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
20980 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
20990 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
209a0 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
209b0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
209c0 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
209d0 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
209e0 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
209f0 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
20a00 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
20a10 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
20a20 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
20a30 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
20a40 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
20a50 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
20a60 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
20a70 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
20a80 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
20a90 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
20aa0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
20ab0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
20ac0 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
20ad0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
20ae0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
20af0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
20b00 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
20b10 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
20b20 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
20b30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
20b40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20b50 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
20b60 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
20b70 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
20b80 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
20b90 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
20ba0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
20bb0 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
20bc0 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
20bd0 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
20be0 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
20bf0 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
20c00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20c10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20c20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
20c30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
20c40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
20c50 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
20c60 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
20c70 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
20c80 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
20c90 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
20ca0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
20cb0 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
20cc0 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
20cd0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
20ce0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20cf0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
20d00 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
20d10 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
20d20 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
20d30 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
20d40 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
20d50 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
20d60 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
20d70 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
20d80 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20d90 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
20da0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
20db0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
20dc0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
20dd0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20de0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
20df0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
20e00 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
20e10 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20e20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20e30 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
20e40 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
20e50 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
20e60 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
20e70 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20e80 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
20e90 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
20ea0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
20eb0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20ec0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20ed0 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
20ee0 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
20ef0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20f00 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20f10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20f20 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
20f30 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
20f40 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
20f50 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20f60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20f70 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
20f80 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
20f90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
20fa0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20fb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20fc0 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
20fd0 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
20fe0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
20ff0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21000 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21010 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
21020 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
21030 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
21040 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21050 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21060 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
21070 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
21080 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
21090 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
210a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
210b0 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
210c0 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
210d0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
210e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
210f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21100 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
21110 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
21120 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
21130 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21140 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21150 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
21160 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
21170 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
21180 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21190 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
211a0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
211b0 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
211c0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
211d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
211e0 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
211f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
21200 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
21210 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
21220 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
21230 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
21240 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
21250 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21260 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
21270 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
21280 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
21290 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
212a0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
212b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
212c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
212d0 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
212e0 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
212f0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
21300 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21310 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21320 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
21330 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
21340 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21350 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
21360 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21370 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
21380 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
21390 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
213a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
213b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
213c0 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
213d0 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
213e0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
213f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21400 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21410 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
21420 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
21430 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
21440 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21450 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21460 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
21470 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
21480 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
21490 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
214a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
214b0 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
214c0 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
214d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
214e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
214f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21500 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
21510 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
21520 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
21530 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
21540 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21550 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
21560 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
21570 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
21580 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
21590 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
215a0 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
215b0 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
215c0 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
215d0 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
215e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
215f0 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
21600 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
21610 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
21620 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
21630 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
21640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21650 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
21660 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
21670 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53  ne SQLITE_RECURS
21680 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33  IVE            3
21690 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  3   /* NULL     
216a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
216b0 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a         */../*.**
216c0 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
216d0 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
216e0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
216f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
21700 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
21710 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
21720 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
21730 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
21740 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
21750 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
21760 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
21770 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
21780 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
21790 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
217a0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
217b0 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
217c0 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
217d0 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
217e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
217f0 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
21800 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
21810 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
21820 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
21830 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
21840 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
21850 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
21860 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
21870 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
21880 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
21890 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
218a0 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
218b0 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
218c0 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
218d0 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
218e0 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
218f0 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
21900 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
21910 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
21920 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
21930 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
21940 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
21950 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  r.)^.**.** The [
21960 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
21970 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
21980 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e  -time option can
21990 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69   be used to limi
219a0 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20  t.** the length 
219b0 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
219c0 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69  ter] expansion i
219d0 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  n the output of 
219e0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e  sqlite3_trace().
219f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
21a00 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
21a10 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
21a20 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
21a30 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
21a40 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
21a50 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
21a60 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
21a70 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
21a80 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
21a90 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
21aa0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
21ab0 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
21ac0 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
21ad0 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
21ae0 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
21af0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
21b00 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
21b10 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
21b20 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
21b30 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
21b40 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
21b50 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
21b60 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
21b70 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
21b80 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
21b90 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
21ba0 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
21bb0 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
21bc0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
21bd0 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
21be0 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
21bf0 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
21c00 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
21c10 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
21c20 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
21c30 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
21c40 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
21c50 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
21c60 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
21c70 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
21c80 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
21c90 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c  TE_API void *SQL
21ca0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
21cb0 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
21cc0 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
21cd0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
21ce0 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
21cf0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
21d00 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
21d10 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
21d20 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  L sqlite3_profil
21d30 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
21d40 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
21d50 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
21d60 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
21d70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
21d80 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
21d90 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
21da0 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  cks.** METHOD: s
21db0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
21dc0 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
21dd0 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
21de0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
21df0 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
21e00 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
21e10 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
21e20 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
21e30 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
21e40 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
21e50 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
21e60 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
21e70 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
21e80 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
21e90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21ea0 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
21eb0 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
21ec0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
21ed0 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
21ee0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
21ef0 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
21f00 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
21f10 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
21f20 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
21f30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
21f40 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
21f50 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
21f60 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
21f70 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e  he approximate n
21f80 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
21f90 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
21fa0 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
21fb0 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
21fc0 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
21fd0 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
21fe0 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
21ff0 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65   X.  ^If N is le
22000 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e  ss than one then
22010 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a   the progress.**
22020 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61   handler is disa
22030 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  bled..**.** ^Onl
22040 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
22050 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
22060 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
22070 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
22080 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22090 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
220a0 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
220b0 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
220c0 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
220d0 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
220e0 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
220f0 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
22100 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
22110 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
22120 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
22130 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
22140 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
22150 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
22160 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
22170 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
22180 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
22190 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
221a0 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
221b0 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
221c0 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
221d0 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
221e0 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
221f0 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
22200 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
22210 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
22220 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
22230 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
22240 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
22250 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
22260 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
22270 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
22280 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
22290 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
222a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
222b0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
222c0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
222d0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
222e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
222f0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
22300 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
22310 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
22320 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ..**.*/.SQLITE_A
22330 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53  PI void SQLITE_S
22340 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70  TDCALL sqlite3_p
22350 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
22360 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
22370 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
22380 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
22390 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
223a0 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
223b0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53  nnection.** CONS
223c0 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
223d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
223e0 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
223f0 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
22400 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
22410 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
22420 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
22430 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
22440 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
22450 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
22460 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
22470 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
22480 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
22490 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
224a0 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
224b0 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
224c0 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
224d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
224e0 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
224f0 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
22500 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
22510 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
22520 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
22530 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
22540 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
22550 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
22560 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
22570 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
22580 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
22590 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
225a0 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
225b0 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
225c0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
225d0 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
225e0 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
225f0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
22600 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
22610 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
22620 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
22630 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
22640 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
22650 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
22660 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
22670 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
22680 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
22690 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
226a0 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
226b0 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
226c0 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
226d0 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
226e0 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
226f0 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
22700 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
22710 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
22720 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
22730 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
22740 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  ng will be UTF-8
22750 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63   for databases c
22760 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
22770 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
22780 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
22790 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75  2().  ^The defau
227a0 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
227b0 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65  databases.** cre
227c0 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  ated using sqlit
227d0 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c  e3_open16() will
227e0 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68   be UTF-16 in th
227f0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
22800 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  der..**.** Wheth
22810 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
22820 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
22830 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
22840 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
22850 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
22860 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22870 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
22880 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
22890 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
228a0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
228b0 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
228c0 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
228d0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
228e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
228f0 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
22900 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
22910 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
22920 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
22930 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
22940 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
22950 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
22960 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
22970 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22980 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
22990 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
229a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
229b0 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
229c0 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
229d0 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
229e0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
229f0 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
22a00 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
22a10 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
22a20 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
22a30 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
22a40 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
22a50 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
22a60 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
22a70 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
22a80 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
22a90 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
22aa0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
22ab0 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
22ac0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
22ad0 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
22ae0 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
22af0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
22b00 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
22b10 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
22b20 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
22b30 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
22b40 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
22b50 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
22b60 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
22b70 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
22b80 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
22b90 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
22ba0 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
22bb0 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
22bc0 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
22bd0 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
22be0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
22bf0 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
22c00 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
22c10 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
22c20 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
22c30 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
22c40 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
22c50 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
22c60 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
22c70 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
22c80 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
22c90 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
22ca0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
22cb0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
22cc0 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
22cd0 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
22ce0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
22cf0 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
22d00 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
22d10 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
22d20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
22d30 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
22d40 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
22d50 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
22d60 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
22d70 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
22d80 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
22d90 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
22da0 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
22db0 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
22dc0 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
22dd0 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
22de0 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
22df0 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
22e00 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
22e10 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
22e20 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
22e30 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
22e40 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
22e50 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
22e60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22e70 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
22e80 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
22e90 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
22ea0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
22eb0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
22ec0 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
22ed0 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
22ee0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
22ef0 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
22f00 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
22f10 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
22f20 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
22f30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22f40 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
22f50 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
22f60 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
22f70 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
22f80 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
22f90 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
22fa0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
22fb0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
22fc0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
22fd0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
22fe0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
22ff0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23000 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
23010 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
23020 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
23030 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
23040 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
23050 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
23060 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
23070 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
23080 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
23090 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
230a0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
230b0 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
230c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
230d0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
230e0 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
230f0 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
23100 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
23110 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
23120 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
23130 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
23140 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
23150 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
23160 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
23170 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
23180 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
23190 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
231a0 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
231b0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
231c0 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
231d0 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
231e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
231f0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
23200 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
23210 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
23220 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
23230 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
23240 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
23250 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
23260 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
23270 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
23280 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
23290 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
232a0 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
232b0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
232c0 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
232d0 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
232e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
232f0 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
23300 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
23310 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
23320 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
23330 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
23340 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
23350 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
23360 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
23370 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
23380 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
23390 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
233a0 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
233b0 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
233c0 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
233d0 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
233e0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
233f0 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
23400 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
23410 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
23420 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
23430 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
23440 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
23450 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
23460 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
23470 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
23480 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
23490 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
234a0 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
234b0 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
234c0 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
234d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
234e0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
234f0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
23500 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
23510 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
23520 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
23530 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
23540 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
23550 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
23560 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
23570 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
23580 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
23590 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
235a0 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
235b0 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
235c0 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
235d0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
235e0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
235f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
23600 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
23610 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61   in the fourth a
23620 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
23630 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72  e3_open_v2(), or
23640 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65   if it has.** be
23650 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61  en enabled globa
23660 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53  lly using the [S
23670 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
23680 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68  ] option with th
23690 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
236a0 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f  nfig()] method o
236b0 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  r by the [SQLITE
236c0 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c  _USE_URI] compil
236d0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
236e0 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76  * As of SQLite v
236f0 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52  ersion 3.7.7, UR
23700 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  I filename inter
23710 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72  pretation is tur
23720 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65  ned off.** by de
23730 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72  fault, but futur
23740 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
23750 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c  Lite might enabl
23760 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a  e URI filename.*
23770 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  * interpretation
23780 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65   by default.  Se
23790 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  e "[URI filename
237a0 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  s]" for addition
237b0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
237c0 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c  n..**.** URI fil
237d0 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65  enames are parse
237e0 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52  d according to R
237f0 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65  FC 3986. ^If the
23800 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e   URI contains an
23810 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74  .** authority, t
23820 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65  hen it must be e
23830 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73  ither an empty s
23840 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72  tring or the str
23850 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f  ing .** "localho
23860 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74  st". ^If the aut
23870 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e  hority is not an
23880 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
23890 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e   "localhost", an
238a0 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65   .** error is re
238b0 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61  turned to the ca
238c0 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d  ller. ^The fragm
238d0 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ent component of
238e0 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70   a URI, if .** p
238f0 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72  resent, is ignor
23900 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
23910 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20  e uses the path 
23920 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65  component of the
23930 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65   URI as the name
23940 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c   of the disk fil
23950 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61  e.** which conta
23960 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ins the database
23970 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62  . ^If the path b
23980 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27  egins with a '/'
23990 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20   character, .** 
239a0 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72  then it is inter
239b0 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73  preted as an abs
239c0 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20  olute path. ^If 
239d0 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f  the path does no
239e0 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68  t begin .** with
239f0 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20   a '/' (meaning 
23a00 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
23a10 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d  ty section is om
23a20 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55  itted from the U
23a30 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  RI).** then the 
23a40 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65  path is interpre
23a50 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76  ted as a relativ
23a60 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e  e path. .** ^(On
23a70 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
23a80 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
23a90 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
23aa0 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
23ab0 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
23ac0 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a  e.g. "C:").)^.**
23ad0 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71  .** [[core URI q
23ae0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d  uery parameters]
23af0 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63  ].** The query c
23b00 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
23b10 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61  I may contain pa
23b20 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
23b30 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a  e interpreted.**
23b40 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74   either by SQLit
23b50 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20  e itself, or by 
23b60 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20  a [VFS | custom 
23b70 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
23b80 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61  on]..** SQLite a
23b90 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20  nd its built-in 
23ba0 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65  [VFSes] interpre
23bb0 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  t the.** followi
23bc0 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ng query paramet
23bd0 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
23be0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
23bf0 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
23c00 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
23c10 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
23c20 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
23c30 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
23c40 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
23c50 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
23c60 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
23c70 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
23c80 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
23c90 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
23ca0 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
23cb0 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
23cc0 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
23cd0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
23ce0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
23cf0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
23d00 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
23d10 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
23d20 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
23d30 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
23d40 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
23d50 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
23d60 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
23d70 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
23d80 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
23d90 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
23da0 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
23db0 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
23dc0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
23dd0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
23de0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23df0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
23e00 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
23e10 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
23e20 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
23e30 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
23e40 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22  w",.**     "rwc"
23e50 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41  , or "memory". A
23e60 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74  ttempting to set
23e70 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72   it to any other
23e80 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20   value is.**    
23e90 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
23ea0 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
23eb0 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
23ec0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
23ed0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
23ee0 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
23ef0 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
23f00 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
23f10 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
23f20 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
23f30 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
23f40 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
23f50 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23f60 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
23f70 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
23f80 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
23f90 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
23fa0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
23fb0 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
23fc0 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
23fd0 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
23fe0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
23ff0 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
24000 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
24010 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
24020 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
24030 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
24040 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
24050 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
24060 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
24070 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
24080 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74  N_CREATE.  ^If t
24090 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
240a0 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20  s.**     set to 
240b0 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20  "memory" then a 
240c0 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  pure [in-memory 
240d0 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e  database] that n
240e0 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20  ever reads.**   
240f0 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d    or writes from
24100 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e   disk is used. ^
24110 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
24120 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
24130 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65  e for.**     the
24140 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
24150 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73  that is less res
24160 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
24170 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  at specified by.
24180 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73  **     the flags
24190 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74   passed in the t
241a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
241b0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
241c0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
241d0 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20  > <b>cache</b>: 
241e0 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d  ^The cache param
241f0 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
24200 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65  to either "share
24210 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72  d" or.**     "pr
24220 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67  ivate". ^Setting
24230 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20   it to "shared" 
24240 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
24250 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20   setting the.** 
24260 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
24270 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20  SHAREDCACHE bit 
24280 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  in the flags arg
24290 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a  ument passed to.
242a0 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f  **     sqlite3_o
242b0 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69  pen_v2(). ^Setti
242c0 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72  ng the cache par
242d0 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61  ameter to "priva
242e0 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65  te" is .**     e
242f0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
24300 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  ting the SQLITE_
24310 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
24320 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49  E bit..**     ^I
24330 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
24340 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
24350 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61  the "cache" para
24360 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74  meter is present
24370 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49   in.**     a URI
24380 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76   filename, its v
24390 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61  alue overrides a
243a0 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75  ny behavior requ
243b0 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67  ested by setting
243c0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
243d0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
243e0 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   or SQLITE_OPEN_
243f0 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67  SHAREDCACHE flag
24400 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
24410 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20  >psow</b>: ^The 
24420 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69  psow parameter i
24430 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72  ndicates whether
24440 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20   or not the.**  
24450 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76     [powersafe ov
24460 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74  erwrite] propert
24470 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e  y does or does n
24480 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a  ot apply to the.
24490 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d  **     storage m
244a0 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68  edia on which th
244b0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
244c0 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20  resides..**.**  
244d0 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f  <li> <b>nolock</
244e0 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20  b>: ^The nolock 
244f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
24500 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72  oolean query par
24510 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68  ameter.**     wh
24520 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62  ich if set disab
24530 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67  les file locking
24540 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75   in rollback jou
24550 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69  rnal modes.  Thi
24560 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66  s.**     is usef
24570 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67  ul for accessing
24580 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61   a database on a
24590 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74   filesystem that
245a0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20   does not.**    
245b0 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67   support locking
245c0 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74  .  Caution:  Dat
245d0 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
245e0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
245f0 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d   two.**     or m
24600 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72  ore processes wr
24610 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20  ite to the same 
24620 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79  database and any
24630 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a   one of those.**
24640 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75       processes u
24650 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a  ses nolock=1..**
24660 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d  .**  <li> <b>imm
24670 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65  utable</b>: ^The
24680 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d   immutable param
24690 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
246a0 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70  n query.**     p
246b0 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e  arameter that in
246c0 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
246d0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
246e0 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20  s stored on.**  
246f0 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64     read-only med
24700 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74  ia.  ^When immut
24710 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c  able is set, SQL
24720 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
24730 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61   the.**     data
24740 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74  base file cannot
24750 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65   be changed, eve
24760 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77  n by a process w
24770 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20  ith higher.**   
24780 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64    privilege, and
24790 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   so the database
247a0 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d   is opened read-
247b0 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63  only and all loc
247c0 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20  king.**     and 
247d0 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e  change detection
247e0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43   is disabled.  C
247f0 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20  aution: Setting 
24800 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a  the immutable.**
24810 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e       property on
24820 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
24830 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61   that does in fa
24840 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65  ct change can re
24850 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69  sult.**     in i
24860 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72  ncorrect query r
24870 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53  esults and/or [S
24880 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65  QLITE_CORRUPT] e
24890 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65  rrors..**     Se
248a0 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f  e also: [SQLITE_
248b0 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d  IOCAP_IMMUTABLE]
248c0 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c  ..**       .** <
248d0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
248e0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
248f0 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
24900 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
24910 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
24920 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
24930 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
24940 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
24950 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
24960 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
24970 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
24980 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
24990 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
249a0 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
249b0 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
249c0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
249d0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
249e0 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
249f0 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
24a00 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
24a10 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
24a20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
24a30 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
24a40 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
24a50 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
24a60 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
24a70 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
24a80 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
24a90 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
24aa0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
24ab0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
24ac0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
24ad0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
24ae0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
24af0 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
24b00 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
24b10 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
24b20 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
24b30 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
24b40 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
24b50 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
24b60 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
24b70 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
24b80 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
24b90 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
24ba0 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
24bb0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
24bc0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
24bd0 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
24be0 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
24bf0 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
24c00 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
24c10 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
24c20 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
24c30 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
24c40 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
24c50 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
24c60 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
24c70 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
24c80 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
24c90 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
24ca0 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
24cb0 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
24cc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
24cd0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
24ce0 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
24cf0 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
24d00 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
24d10 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
24d20 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
24d30 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
24d40 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
24d50 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
24d60 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
24d70 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
24d80 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
24d90 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
24da0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
24db0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
24dc0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
24dd0 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
24de0 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
24df0 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
24e00 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
24e10 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
24e20 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
24e30 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
24e40 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
24e50 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
24e60 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
24e70 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
24e80 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64  ta.db?vfs=unix-d
24e90 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20  otfile <td>.**  
24ea0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
24eb0 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
24ec0 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20  ta.db". Use the 
24ed0 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69  special VFS "uni
24ee0 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20  x-dotfile".**   
24ef0 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73         that uses
24f00 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c   dot-files in pl
24f10 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76  ace of posix adv
24f20 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a  isory locking..*
24f30 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
24f40 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61  data.db?mode=rea
24f50 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20  donly <td> .**  
24f60 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
24f70 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20  . "readonly" is 
24f80 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69  not a valid opti
24f90 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65  on for the "mode
24fa0 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  " parameter..** 
24fb0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e  </table>.**.** ^
24fc0 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20  URI hexadecimal 
24fd0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
24fe0 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f   (%HH) are suppo
24ff0 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20  rted within the 
25000 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72  path and.** quer
25010 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
25020 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63  a URI. A hexadec
25030 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
25040 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66  ence consists of
25050 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69   a.** percent si
25060 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f  gn - "%" - follo
25070 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74  wed by exactly t
25080 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  wo hexadecimal d
25090 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66  igits .** specif
250a0 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61  ying an octet va
250b0 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65  lue. ^Before the
250c0 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63   path or query c
250d0 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a  omponents of a.*
250e0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61  * URI filename a
250f0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20  re interpreted, 
25100 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64  they are encoded
25110 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64   using UTF-8 and
25120 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63   all .** hexadec
25130 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
25140 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62  ences replaced b
25150 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20  y a single byte 
25160 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a  containing the.*
25170 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  * corresponding 
25180 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70  octet. If this p
25190 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73  rocess generates
251a0 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d   an invalid UTF-
251b0 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74  8 encoding,.** t
251c0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
251d0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
251e0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
251f0 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
25200 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
25210 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
25220 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
25230 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
25240 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
25250 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
25260 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
25270 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
25280 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
25290 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
252a0 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
252b0 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
252c0 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
252d0 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
252e0 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
252f0 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
25300 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
25310 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25320 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ()..**.** <b>Not
25330 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
25340 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
25350 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
25360 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
25370 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
25380 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
25390 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
253a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f  e3_open_v2().  O
253b0 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
253c0 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
253d0 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
253e0 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
253f0 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a  files may fail..
25400 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
25410 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  [sqlite3_temp_di
25420 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49  rectory].*/.SQLI
25430 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
25440 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
25450 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
25460 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
25470 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
25480 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
25490 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
254a0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
254b0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
254c0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  ndle */.);.SQLIT
254d0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
254e0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
254f0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
25500 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
25510 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
25520 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
25530 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
25540 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
25550 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
25560 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c  handle */.);.SQL
25570 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
25580 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
25590 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
255a0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
255b0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
255c0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
255d0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
255e0 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
255f0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
25600 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
25610 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
25620 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
25630 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
25640 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
25650 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
25660 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
25670 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25680 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f  Obtain Values Fo
25690 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73  r URI Parameters
256a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
256b0 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65   utility routine
256c0 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  s, useful to VFS
256d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
256e0 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20  , that check.** 
256f0 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61  to see if a data
25700 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20  base file was a 
25710 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  URI that contain
25720 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75  ed a specific qu
25730 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ery .** paramete
25740 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74  r, and if so obt
25750 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  ains the value o
25760 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72  f that query par
25770 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
25780 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61   F is the databa
25790 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  se filename poin
257a0 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
257b0 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68  the xOpen() meth
257c0 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20  od of .** a VFS 
257d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
257e0 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61  hen the flags pa
257f0 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
25800 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a  () has one or .*
25810 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
25820 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
25830 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
25840 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65  MAIN_DB] bits se
25850 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68  t and.** P is th
25860 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75  e name of the qu
25870 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ery parameter, t
25880 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  hen.** sqlite3_u
25890 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
258a0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  ) returns the va
258b0 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20  lue of the P.** 
258c0 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20  parameter if it 
258d0 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c  exists or a NULL
258e0 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f   pointer if P do
258f0 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73  es not appear as
25900 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   a .** query par
25910 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66  ameter on F.  If
25920 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61   P is a query pa
25930 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20  rameter of F.** 
25940 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20  has no explicit 
25950 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69  value, then sqli
25960 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
25970 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a  r(F,P) returns.*
25980 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
25990 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
259a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
259b0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
259c0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73  P,B) routine ass
259d0 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61  umes that P is a
259e0 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61   boolean.** para
259f0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
25a00 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61  s true (1) or fa
25a10 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e  lse (0) accordin
25a20 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a  g to the value.*
25a30 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c  * of P.  The sql
25a40 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
25a50 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
25a60 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
25a70 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65   if the.** value
25a80 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65   of query parame
25a90 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
25aa0 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f  "yes", "true", o
25ab0 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a  r "on" in any.**
25ac0 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20   case or if the 
25ad0 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
25ae0 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d  h a non-zero num
25af0 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71  ber.  The .** sq
25b00 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
25b10 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
25b20 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  s returns false 
25b30 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65  (0) if the value
25b40 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   of.** query par
25b50 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
25b60 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22  of "no", "false"
25b70 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e  , or "off" in an
25b80 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20  y case or.** if 
25b90 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
25ba0 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20   with a numeric 
25bb0 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e  zero.  If P is n
25bc0 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61  ot a query.** pa
25bd0 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20  rameter on F or 
25be0 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  if the value of 
25bf0 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61  P is does not ma
25c00 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a  tch any of the.*
25c10 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71  * above, then sq
25c20 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
25c30 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
25c40 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54   (B!=0)..**.** T
25c50 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  he sqlite3_uri_i
25c60 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74  nt64(F,P,D) rout
25c70 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ine converts the
25c80 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f   value of P into
25c90 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67   a.** 64-bit sig
25ca0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
25cb0 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74  returns that int
25cc0 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20  eger, or D if P 
25cd0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73  does not.** exis
25ce0 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65  t.  If the value
25cf0 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69   of P is somethi
25d00 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e  ng other than an
25d10 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a   integer, then.*
25d20 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  * zero is return
25d30 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20  ed..** .** If F 
25d40 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
25d50 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
25d60 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
25d70 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  P) returns NULL 
25d80 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
25d90 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
25da0 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66  ) returns B.  If
25db0 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c   F is not a NULL
25dc0 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20   pointer and.** 
25dd0 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
25de0 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  e file pathname 
25df0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
25e00 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ite passed into 
25e10 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53  the xOpen.** VFS
25e20 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
25e30 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
25e40 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e  is routine is un
25e50 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
25e60 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61  ably.** undesira
25e70 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ble..*/.SQLITE_A
25e80 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
25e90 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
25ea0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
25eb0 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ter(const char *
25ec0 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74  zFilename, const
25ed0 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a   char *zParam);.
25ee0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
25ef0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
25f00 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
25f10 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
25f20 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
25f30 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
25f40 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41  fault);.SQLITE_A
25f50 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
25f60 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
25f70 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
25f80 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
25f90 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
25fa0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
25fb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
25fc0 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
25fd0 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ssages.** METHOD
25fe0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
25ff0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
26000 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  ent sqlite3_* AP
26010 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
26020 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61  d with .** [data
26030 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
26040 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20   D failed, then 
26050 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  the sqlite3_errc
26060 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65  ode(D) interface
26070 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
26080 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
26090 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
260a0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
260b0 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20  for that.** API 
260c0 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20  call..** If the 
260d0 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
260e0 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73  call was success
260f0 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ful,.** then the
26100 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
26110 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  om sqlite3_errco
26120 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
26130 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
26140 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
26150 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
26160 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
26170 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
26180 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
26190 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
261a0 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
261b0 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
261c0 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
261d0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
261e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
261f0 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
26200 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
26210 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
26220 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
26230 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
26240 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
26250 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
26260 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
26270 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
26280 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
26290 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
262a0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
262b0 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
262c0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
262d0 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
262e0 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
262f0 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
26300 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
26310 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
26320 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
26330 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
26340 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
26350 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
26360 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
26370 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  tions.)^.**.** ^
26380 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73  The sqlite3_errs
26390 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  tr() interface r
263a0 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69  eturns the Engli
263b0 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
263c0 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62  .** that describ
263d0 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63  es the [result c
263e0 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a  ode], as UTF-8..
263f0 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
26400 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
26410 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
26420 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
26430 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e  ly.** and must n
26440 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74  ot be freed by t
26450 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e  he application)^
26460 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
26470 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
26480 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
26490 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
264a0 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
264b0 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
264c0 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
264d0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
264e0 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
264f0 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
26500 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
26510 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
26520 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
26530 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
26540 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
26550 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
26560 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
26570 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
26580 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
26590 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
265a0 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
265b0 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
265c0 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
265d0 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
265e0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
265f0 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
26600 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
26610 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
26620 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
26630 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
26640 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
26650 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
26660 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
26670 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
26680 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
26690 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
266a0 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
266b0 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
266c0 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
266d0 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
266e0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
266f0 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
26700 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
26710 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
26720 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
26730 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
26740 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
26750 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
26760 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
26770 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
26780 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c  t be set..*/.SQL
26790 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
267a0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
267b0 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
267c0 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
267d0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
267e0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
267f0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
26800 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51  sqlite3 *db);.SQ
26810 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
26820 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
26830 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  ALL sqlite3_errm
26840 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  sg(sqlite3*);.SQ
26850 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
26860 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
26870 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  ALL sqlite3_errm
26880 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
26890 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
268a0 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
268b0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72  DCALL sqlite3_er
268c0 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  rstr(int);../*.*
268d0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70  * CAPI3REF: Prep
268e0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
268f0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
26900 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
26910 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
26920 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
26930 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
26940 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
26950 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
26960 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
26970 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65   that.** has bee
26980 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  n compiled into 
26990 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20  binary form and 
269a0 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 65  is ready to be e
269b0 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  valuated..**.** 
269c0 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51  Think of each SQ
269d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61  L statement as a
269e0 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74   separate comput
269f0 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65  er program.  The
26a00 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
26a10 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 20   text is source 
26a20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 65  code.  A prepare
26a30 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
26a40 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f  ct .** is the co
26a50 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f  mpiled object co
26a60 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73  de.  All SQL mus
26a70 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69  t be converted i
26a80 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65  nto a.** prepare
26a90 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f  d statement befo
26aa0 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e  re it can be run
26ab0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65  ..**.** The life
26ac0 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70  -cycle of a prep
26ad0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
26ae0 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f  bject usually go
26af0 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  es like this:.**
26b00 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
26b10 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65 70   Create the prep
26b20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
26b30 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
26b40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26b50 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  )]..** <li> Bind
26b60 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61   values to [para
26b70 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
26b80 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
26b90 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
26ba0 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
26bb0 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
26bc0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
26bd0 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
26be0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
26bf0 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65 70  > Reset the prep
26c00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
26c10 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
26c20 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
26c30 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
26c40 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
26c50 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
26c60 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
26c70 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
26c80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
26c90 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
26ca0 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ol>.*/.typedef s
26cb0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
26cc0 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
26cd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26ce0 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
26cf0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
26d00 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ite3.**.** ^(Thi
26d10 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
26d20 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
26d30 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
26d40 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
26d50 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
26d60 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
26d70 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
26d80 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
26d90 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
26da0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
26db0 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
26dc0 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
26dd0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
26de0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
26df0 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
26e00 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
26e10 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
26e20 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
26e30 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
26e40 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
26e50 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
26e60 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
26e70 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
26e80 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
26e90 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
26ea0 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
26eb0 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
26ec0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46  nchanged..** ^(F
26ed0 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61  or each limit ca
26ee0 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49  tegory SQLITE_LI
26ef0 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20  MIT_<i>NAME</i> 
26f00 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b  there is a .** [
26f10 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70  limits | hard up
26f20 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65  per bound].** se
26f30 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
26f40 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63  e by a C preproc
26f50 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c  essor macro call
26f60 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  ed.** [limits | 
26f70 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41  SQLITE_MAX_<i>NA
26f80 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65  ME</i>]..** (The
26f90 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
26fa0 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
26fb0 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e  d to "_MAX_".))^
26fc0 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f  .** ^Attempts to
26fd0 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
26fe0 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
26ff0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
27000 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
27010 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
27020 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
27030 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73  **.** ^Regardles
27040 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
27050 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61  not the limit wa
27060 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a  s changed, the .
27070 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ** [sqlite3_limi
27080 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  t()] interface r
27090 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72  eturns the prior
270a0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69   value of the li
270b0 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20  mit..** ^Hence, 
270c0 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72  to find the curr
270d0 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c  ent value of a l
270e0 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61  imit without cha
270f0 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d  nging it,.** sim
27100 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20  ply invoke this 
27110 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74  interface with t
27120 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
27130 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a  er set to -1..**
27140 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d  .** Run-time lim
27150 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
27160 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
27170 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
27180 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
27190 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
271a0 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
271b0 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
271c0 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
271d0 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
271e0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
271f0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
27200 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
27210 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77  be a.** web brow
27220 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
27230 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
27240 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
27250 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
27260 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
27270 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
27280 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
27290 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
272a0 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
272b0 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
272c0 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
272d0 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
272e0 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
272f0 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
27300 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
27310 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
27320 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
27330 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
27340 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
27350 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
27360 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
27370 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
27380 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
27390 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
273a0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
273b0 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
273c0 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
273d0 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
273e0 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
273f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
27400 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
27410 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
27420 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
27430 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
27440 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
27450 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
27460 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
27470 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
27480 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
27490 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
274a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
274b0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
274c0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
274d0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
274e0 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
274f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
27500 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
27510 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
27520 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
27530 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
27540 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
27550 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
27560 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
27570 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
27580 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
27590 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
275a0 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
275b0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
275c0 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
275d0 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
275e0 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
275f0 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
27600 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
27610 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
27620 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
27630 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
27640 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
27650 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
27660 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
27670 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
27680 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
27690 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
276a0 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
276b0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
276c0 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
276d0 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
276e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
276f0 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
27700 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
27710 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
27720 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
27730 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
27740 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
27750 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
27760 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27770 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
27780 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
27790 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
277a0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
277b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
277c0 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
277d0 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
277e0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
277f0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
27800 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
27810 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
27820 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
27830 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
27840 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
27850 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
27860 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
27870 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
27880 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
27890 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
278a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
278b0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
278c0 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
278d0 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
278e0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
278f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
27900 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
27910 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
27920 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
27930 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27940 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
27950 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
27960 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
27970 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
27980 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
27990 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
279a0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
279b0 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
279c0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
279d0 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
279e0 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
279f0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
27a00 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
27a10 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
27a20 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
27a30 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
27a40 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
27a50 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
27a60 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
27a70 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
27a80 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
27a90 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
27aa0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
27ab0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
27ac0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
27ad0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
27ae0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27af0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
27b00 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
27b10 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
27b20 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
27b30 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
27b40 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
27b50 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
27b60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
27b70 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
27b80 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
27b90 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
27ba0 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
27bb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
27bc0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
27bd0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
27be0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
27bf0 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
27c00 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
27c10 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
27c20 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
27c30 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
27c40 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
27c50 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
27c60 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
27c70 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
27c80 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
27c90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
27ca0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
27cb0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
27cc0 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
27cd0 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
27ce0 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
27cf0 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
27d00 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
27d10 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
27d20 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
27d30 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
27d40 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
27d50 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
27d60 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
27d70 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
27d80 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
27d90 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
27da0 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51  READS]] ^(<dt>SQ
27db0 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
27dc0 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a  R_THREADS</dt>.*
27dd0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
27de0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69  m number of auxi
27df0 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72  liary worker thr
27e00 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67  eads that a sing
27e10 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  le.** [prepared 
27e20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73  statement] may s
27e30 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  tart.</dd>)^.** 
27e40 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
27e50 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
27e60 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
27e70 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
27e80 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
27e90 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
27ea0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
27eb0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
27ec0 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
27ed0 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
27ee0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27ef0 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
27f00 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
27f10 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27f20 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
27f30 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
27f40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27f50 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
27f60 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
27f70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
27f80 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
27f90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
27fa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
27fb0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
27fc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
27fd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27fe0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
27ff0 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
28000 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
28010 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
28020 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
28030 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
28040 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
28050 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
28060 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
28070 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
28080 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20  THREADS         
28090 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    11../*.** CAPI
280a0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
280b0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
280c0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
280d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
280e0 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  piler}.** METHOD
280f0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e  : sqlite3.** CON
28100 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
28110 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20  3_stmt.**.** To 
28120 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
28130 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
28140 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
28150 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
28160 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
28170 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
28180 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
28190 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
281a0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
281b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
281c0 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
281d0 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
281e0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
281f0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
28200 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
28210 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
28220 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
28230 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
28240 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
28250 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
28260 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
28270 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
28280 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
28290 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
282a0 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
282b0 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
282c0 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
282d0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
282e0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
282f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
28300 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
28310 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
28320 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
28330 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
28340 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
28350 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
28360 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
28370 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76  ument is negativ
28380 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  e, then zSql is 
28390 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
283a0 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
283b0 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
283c0 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20  te is positive, 
283d0 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a  then it is the.*
283e0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
283f0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
28400 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  .  ^If nByte is 
28410 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72  zero, then no pr
28420 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
28430 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64  ent is generated
28440 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
28450 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68  er knows that th
28460 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
28470 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
28480 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ted, then.** the
28490 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65  re is a small pe
284a0 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
284b0 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61  age to passing a
284c0 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
284d0 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65  r that.** is the
284e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
284f0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
28500 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
28510 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
28520 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a  -terminator..**.
28530 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
28540 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
28550 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
28560 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
28570 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
28580 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
28590 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
285a0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
285b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
285c0 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
285d0 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
285e0 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
285f0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
28600 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
28610 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
28620 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
28630 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
28640 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
28650 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
28660 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
28670 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
28680 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
28690 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
286a0 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
286b0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
286c0 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
286d0 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
286e0 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
286f0 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
28700 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
28710 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
28720 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
28730 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
28740 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
28750 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
28760 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
28770 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
28780 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
28790 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
287a0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
287b0 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
287c0 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
287d0 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
287e0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
287f0 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
28800 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
28810 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
28820 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
28830 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
28840 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
28850 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
28860 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
28870 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
28880 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
28890 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
288a0 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
288b0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
288c0 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
288d0 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
288e0 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
288f0 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
28900 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
28910 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
28920 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
28930 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
28940 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
28950 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
28960 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
28970 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
28980 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
28990 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
289a0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
289b0 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
289c0 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
289d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
289e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
289f0 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
28a00 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
28a10 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
28a20 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
28a30 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
28a40 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
28a50 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
28a60 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
28a70 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
28a80 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
28a90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
28aa0 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
28ab0 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
28ac0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
28ad0 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
28ae0 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e  it again. As man
28af0 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58  y as [SQLITE_MAX
28b00 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a  _SCHEMA_RETRY].*
28b10 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f  * retries will o
28b20 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69  ccur before sqli
28b30 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73  te3_step() gives
28b40 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20   up and returns 
28b50 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c  an error..** </l
28b60 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
28b70 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
28b80 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
28b90 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
28ba0 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
28bb0 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
28bc0 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
28bd0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
28be0 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
28bf0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
28c00 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
28c10 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
28c20 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
28c30 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
28c40 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
28c50 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
28c60 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
28c70 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
28c80 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
28c90 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
28ca0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
28cb0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
28cc0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
28cd0 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
28ce0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
28cf0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
28d00 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
28d10 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
28d20 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
28d30 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
28d40 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
28d50 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
28d60 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
28d70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
28d80 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
28d90 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
28da0 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
28db0 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
28dc0 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
28dd0 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
28de0 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
28df0 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
28e00 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
28e10 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
28e20 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
28e30 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
28e40 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
28e50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
28e60 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
28e70 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
28e80 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
28e90 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
28ea0 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
28eb0 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
28ec0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
28ed0 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
28ee0 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
28ef0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
28f00 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
28f10 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
28f20 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
28f30 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
28f40 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
28f50 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
28f60 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
28f70 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
28f80 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
28f90 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
28fa0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
28fb0 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
28fc0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
28fd0 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  bled..** </li>.*
28fe0 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54  * </ol>.*/.SQLIT
28ff0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
29000 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
29010 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
29020 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
29030 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
29040 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
29050 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
29060 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
29070 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
29080 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
29090 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
290a0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
290b0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
290c0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
290d0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
290e0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
290f0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
29100 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
29110 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
29120 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
29130 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
29140 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
29150 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
29160 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72  DCALL sqlite3_pr
29170 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
29180 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
29190 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
291a0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
291b0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
291c0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
291d0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
291e0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
291f0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
29200 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
29210 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
29220 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
29230 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
29240 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
29250 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
29260 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
29270 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
29280 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
29290 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
292a0 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
292b0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
292c0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72  DCALL sqlite3_pr
292d0 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
292e0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
292f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
29300 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
29310 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
29320 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
29330 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
29340 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
29350 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
29360 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
29370 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
29380 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
29390 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
293a0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
293b0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
293c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
293d0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
293e0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
293f0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
29400 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
29410 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
29420 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72  DCALL sqlite3_pr
29430 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
29440 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
29450 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
29460 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
29470 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
29480 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
29490 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
294a0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
294b0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
294c0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
294d0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
294e0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
294f0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
29500 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
29510 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
29520 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
29530 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
29540 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
29550 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
29560 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
29570 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
29580 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
29590 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   SQL.** METHOD: 
295a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
295b0 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
295c0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
295d0 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
295e0 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
295f0 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
29600 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
29610 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
29620 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
29630 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
29640 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
29650 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
29660 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
29670 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
29680 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  are16_v2()]..*/.
29690 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
296a0 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
296b0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 71  DCALL sqlite3_sq
296c0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
296d0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
296e0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
296f0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
29700 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68  tement Writes Th
29710 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45  e Database.** ME
29720 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
29730 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
29740 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
29750 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65  nly(X) interface
29760 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
29770 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61  on-zero) if.** a
29780 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
29790 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
297a0 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64  nt] X makes no d
297b0 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  irect changes to
297c0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
297d0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
297e0 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  file..**.** Note
297f0 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69   that [applicati
29800 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
29810 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20  unctions] or.** 
29820 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
29830 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68   might change th
29840 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72  e database indir
29850 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20  ectly as a side 
29860 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46  effect.  .** ^(F
29870 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
29880 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
29890 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e  fines a function
298a0 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a   "eval()" that .
298b0 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  ** calls [sqlite
298c0 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20  3_exec()], then 
298d0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
298e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c  L statement woul
298f0 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  d.** change the 
29900 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
29910 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63  rough side-effec
29920 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ts:.**.** <block
29930 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
29940 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44    SELECT eval('D
29950 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20  ELETE FROM t1') 
29960 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72  FROM t2;.** </pr
29970 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
29980 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73  **.** But becaus
29990 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  e the [SELECT] s
299a0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
299b0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
299c0 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69  abase file.** di
299d0 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f  rectly, sqlite3_
299e0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
299f0 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75  would still retu
29a00 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  rn true.)^.**.**
29a10 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f   ^Transaction co
29a20 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73  ntrol statements
29a30 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d   such as [BEGIN]
29a40 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c  , [COMMIT], [ROL
29a50 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LBACK],.** [SAVE
29a60 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c  POINT], and [REL
29a70 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69  EASE] cause sqli
29a80 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
29a90 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
29aa0 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ue,.** since the
29ab0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d   statements them
29ac0 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63  selves do not ac
29ad0 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68  tually modify th
29ae0 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a  e database but.*
29af0 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f  * rather they co
29b00 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67  ntrol the timing
29b10 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73   of when other s
29b20 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79  tatements modify
29b30 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73   the .** databas
29b40 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48  e.  ^The [ATTACH
29b50 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73  ] and [DETACH] s
29b60 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63  tatements also c
29b70 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ause.** sqlite3_
29b80 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
29b90 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  to return true s
29ba0 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73  ince, while thos
29bb0 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
29bc0 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69  change the confi
29bd0 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61  guration of a da
29be0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29bf0 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d  n, they do not m
29c00 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20  ake .** changes 
29c10 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  to the content o
29c20 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
29c30 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f  iles on disk..*/
29c40 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29c50 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
29c60 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
29c70 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
29c80 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
29c90 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
29ca0 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61  rmine If A Prepa
29cb0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61  red Statement Ha
29cc0 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20  s Been Reset.** 
29cd0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
29ce0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
29cf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
29d00 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(S) interface r
29d10 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
29d20 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a  -zero) if the.**
29d30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29d40 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e  ment] S has been
29d50 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73   stepped at leas
29d60 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a  t once using .**
29d70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
29d80 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74 68  )] but has neith
29d90 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  er run to comple
29da0 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a  tion (returned.*
29db0 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20  * [SQLITE_DONE] 
29dc0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74  from [sqlite3_st
29dd0 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62  ep(S)]) nor.** b
29de0 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20  een reset using 
29df0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
29e00 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  )].  ^The sqlite
29e10 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a  3_stmt_busy(S).*
29e20 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
29e30 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69  rns false if S i
29e40 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
29e50 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61  .  If S is not a
29e60 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   .** NULL pointe
29e70 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  r and is not a p
29e80 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
29e90 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
29ea0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
29eb0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
29ec0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
29ed0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
29ee0 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
29ef0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
29f00 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63  can be used in c
29f10 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69  ombination [sqli
29f20 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
29f30 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  .** to locate al
29f40 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
29f50 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
29f60 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
29f70 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   .** connection 
29f80 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64  that are in need
29f90 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e   of being reset.
29fa0 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
29fb0 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70  ed,.** for examp
29fc0 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69  le, in diagnosti
29fd0 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65  c routines to se
29fe0 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65  arch for prepare
29ff0 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  d .** statements
2a000 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e   that are holdin
2a010 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
2a020 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  open..*/.SQLITE_
2a030 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2a040 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73  TDCALL sqlite3_s
2a050 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
2a060 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2a070 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
2a080 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
2a090 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
2a0a0 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
2a0b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
2a0c0 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
2a0d0 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
2a0e0 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2a0f0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2a100 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
2a110 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
2a120 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
2a130 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
2a140 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
2a150 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
2a160 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
2a170 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
2a180 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
2a190 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
2a1a0 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
2a1b0 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
2a1c0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2a1d0 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
2a1e0 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
2a1f0 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
2a200 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
2a210 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
2a220 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
2a230 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
2a240 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2a250 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
2a260 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2a270 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
2a280 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
2a290 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
2a2a0 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
2a2b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2a2c0 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
2a2d0 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
2a2e0 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
2a2f0 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
2a300 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
2a310 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
2a320 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
2a330 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2a340 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
2a350 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74  value_dup()] int
2a360 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2a370 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20  ed to construct 
2a380 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63  a new .** protec
2a390 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2a3a0 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74  e from an unprot
2a3b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2a3c0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
2a3d0 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
2a3e0 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
2a3f0 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
2a400 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
2a410 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
2a420 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
2a430 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
2a440 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2a450 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2a460 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
2a470 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
2a480 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2a490 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2a4a0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
2a4b0 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
2a4c0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
2a4d0 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
2a4e0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
2a4f0 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
2a500 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
2a510 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
2a520 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
2a530 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
2a540 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
2a550 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
2a560 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2a570 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
2a580 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
2a590 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
2a5a0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
2a5b0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
2a5c0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
2a5d0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2a5e0 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
2a5f0 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
2a600 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
2a610 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
2a620 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
2a630 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
2a640 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
2a650 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
2a660 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
2a670 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
2a680 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
2a690 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
2a6a0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2a6b0 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
2a6c0 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
2a6d0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
2a6e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2a6f0 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
2a700 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
2a710 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
2a720 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
2a730 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
2a740 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2a750 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
2a760 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
2a770 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2a780 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2a790 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2a7a0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2a7b0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
2a7c0 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
2a7d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2a7e0 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
2a7f0 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
2a800 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2a810 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
2a820 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2a830 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
2a840 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
2a850 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2a860 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
2a870 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
2a880 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
2a890 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2a8a0 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
2a8b0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
2a8c0 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
2a8d0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
2a8e0 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
2a8f0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
2a900 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
2a910 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
2a920 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
2a930 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
2a940 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2a950 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
2a960 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
2a970 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
2a980 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
2a990 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
2a9a0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2a9b0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2a9c0 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
2a9d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2a9e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
2a9f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
2aa00 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
2aa10 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
2aa20 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
2aa30 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
2aa40 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
2aa50 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2aa60 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2aa70 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
2aa80 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
2aa90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2aaa0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
2aab0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
2aac0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
2aad0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
2aae0 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
2aaf0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2ab00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
2ab10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
2ab20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ab30 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
2ab40 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
2ab50 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
2ab60 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
2ab70 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
2ab80 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
2ab90 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
2aba0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
2abb0 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
2abc0 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
2abd0 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
2abe0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2abf0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  _stmt.**.** ^(In
2ac00 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2ac10 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
2ac20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ac30 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
2ac40 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
2ac50 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
2ac60 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
2ac70 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
2ac80 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
2ac90 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
2aca0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2acb0 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
2acc0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
2acd0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
2ace0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
2acf0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2ad00 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
2ad10 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
2ad20 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
2ad30 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
2ad40 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
2ad50 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
2ad60 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
2ad70 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
2ad80 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
2ad90 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
2ada0 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
2adb0 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
2adc0 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
2add0 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
2ade0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2adf0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
2ae00 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
2ae10 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2ae20 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
2ae30 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2ae40 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
2ae50 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
2ae60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2ae70 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
2ae80 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
2ae90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2aea0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
2aeb0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
2aec0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2aed0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2aee0 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
2aef0 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
2af00 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
2af10 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2af20 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
2af30 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
2af40 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
2af50 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
2af60 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
2af70 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2af80 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
2af90 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
2afa0 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
2afb0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
2afc0 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
2afd0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
2afe0 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
2aff0 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
2b000 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2b010 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2b020 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
2b030 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
2b040 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
2b050 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
2b060 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
2b070 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
2b080 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
2b090 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
2b0a0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
2b0b0 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
2b0c0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2b0d0 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
2b0e0 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
2b0f0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
2b100 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
2b110 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
2b120 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
2b130 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2b140 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2b150 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2b160 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2b170 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
2b180 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2b190 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2b1a0 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
2b1b0 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
2b1c0 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
2b1d0 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
2b1e0 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
2b1f0 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
2b200 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
2b210 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
2b220 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
2b230 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
2b240 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2b250 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2b260 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
2b270 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
2b280 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2b290 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
2b2a0 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
2b2b0 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
2b2c0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2b2d0 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
2b2e0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2b2f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2b300 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2b310 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2b320 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
2b330 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
2b340 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
2b350 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
2b360 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
2b370 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
2b380 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
2b390 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2b3a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2b3b0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2b3c0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
2b3d0 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
2b3e0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2b3f0 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
2b400 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2b410 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
2b420 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2b430 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
2b440 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2b450 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2b460 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a  d_text64() then.
2b470 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  ** that paramete
2b480 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
2b490 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
2b4a0 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
2b4b0 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
2b4c0 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
2b4d0 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
2b4e0 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
2b4f0 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
2b500 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
2b510 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
2b520 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
2b530 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
2b540 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
2b550 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
2b560 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
2b570 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
2b580 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
2b590 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
2b5a0 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
2b5b0 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
2b5c0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
2b5d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2b5e0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
2b5f0 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42  ment to the BLOB
2b600 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64   and string bind
2b610 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ing interfaces.*
2b620 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  * is a destructo
2b630 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
2b640 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2b650 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
2b660 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
2b670 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
2b680 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2b690 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
2b6a0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2b6b0 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
2b6c0 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
2b6d0 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e   bind API fails.
2b6e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2b6f0 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
2b700 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
2b710 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
2b720 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
2b730 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
2b740 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
2b750 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
2b760 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
2b770 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
2b780 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
2b790 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2b7a0 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
2b7b0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
2b7c0 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
2b7d0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
2b7e0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
2b7f0 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
2b800 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
2b810 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
2b820 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2b830 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
2b840 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67  * ^The sixth arg
2b850 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2b860 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d  _bind_text64() m
2b870 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a  ust be one of.**
2b880 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
2b890 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
2b8a0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2b8b0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
2b8c0 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63  16LE].** to spec
2b8d0 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ify the encoding
2b8e0 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20   of the text in 
2b8f0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2b900 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ter.  If.** the 
2b910 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2b920 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2b930 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f  ext64() is not o
2b940 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c  ne of the.** all
2b950 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77  owed values show
2b960 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74  n above, or if t
2b970 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
2b980 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a   is different.**
2b990 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69   from the encodi
2b9a0 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ng specified by 
2b9b0 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65  the sixth parame
2b9c0 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ter, then the be
2b9d0 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
2b9e0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2b9f0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2ba00 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
2ba10 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
2ba20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
2ba30 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
2ba40 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
2ba50 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
2ba60 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
2ba70 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
2ba80 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
2ba90 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
2baa0 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
2bab0 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
2bac0 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
2bad0 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
2bae0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2baf0 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
2bb00 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
2bb10 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
2bb20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
2bb30 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
2bb40 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
2bb50 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
2bb60 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
2bb70 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
2bb80 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
2bb90 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
2bba0 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
2bbb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2bbc0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2bbd0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
2bbe0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
2bbf0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2bc00 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
2bc10 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2bc20 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
2bc30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2bc40 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
2bc50 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
2bc60 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
2bc70 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
2bc80 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
2bc90 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
2bca0 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
2bcb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
2bcc0 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
2bcd0 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
2bce0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2bcf0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2bd00 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
2bd10 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
2bd20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
2bd30 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
2bd40 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
2bd50 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
2bd60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
2bd70 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
2bd80 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
2bd90 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
2bda0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
2bdb0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2bdc0 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
2bdd0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
2bde0 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
2bdf0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
2be00 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
2be10 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
2be20 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74  TE_TOOBIG] might
2be30 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
2be40 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74  the size of a st
2be50 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20  ring or BLOB.** 
2be60 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69  exceeds limits i
2be70 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  mposed by [sqlit
2be80 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2be90 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29  E_LIMIT_LENGTH])
2bea0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d   or.** [SQLITE_M
2beb0 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e  AX_LENGTH]..** ^
2bec0 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
2bed0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
2bee0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
2bef0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2bf00 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
2bf10 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
2bf20 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
2bf30 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
2bf40 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2bf50 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2bf60 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
2bf70 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2bf80 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
2bf90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2bfa0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2bfb0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2bfc0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2bfd0 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2bfe0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2bff0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2c000 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
2c010 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
2c020 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2c030 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2c040 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28  te3_bind_blob64(
2c050 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c060 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2c070 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2c080 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2c090 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
2c0a0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
2c0b0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2c0c0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2c0d0 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
2c0e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2c0f0 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f  double);.SQLITE_
2c100 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2c110 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2c120 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
2c130 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
2c140 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2c150 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2c160 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2c170 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2c180 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
2c190 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
2c1a0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2c1b0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2c1c0 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
2c1d0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  tmt*, int);.SQLI
2c1e0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2c1f0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2c200 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
2c210 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
2c220 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
2c230 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
2c240 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2c250 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2c260 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2c270 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c280 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2c290 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2c2a0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2c2b0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2c2c0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2c2d0 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65  nd_text64(sqlite
2c2e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2c2f0 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
2c300 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2c310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c320 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
2c330 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61  *), unsigned cha
2c340 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c  r encoding);.SQL
2c350 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2c360 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2c370 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
2c380 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c390 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
2c3a0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
2c3b0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2c3c0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2c3d0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
2c3e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2c3f0 20 69 6e 74 20 6e 29 3b 0a 53 51 4c 49 54 45 5f   int n);.SQLITE_
2c400 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2c410 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2c420 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73  ind_zeroblob64(s
2c430 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2c440 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  t, sqlite3_uint6
2c450 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
2c460 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
2c470 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
2c480 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2c490 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  _stmt.**.** ^Thi
2c4a0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
2c4b0 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
2c4c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
2c4d0 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
2c4e0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
2c4f0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
2c500 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
2c510 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
2c520 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
2c530 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
2c540 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
2c550 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
2c560 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
2c570 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
2c580 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2c590 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
2c5a0 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
2c5b0 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
2c5c0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
2c5d0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
2c5e0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
2c5f0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
2c600 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
2c610 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
2c620 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
2c630 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
2c640 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
2c650 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
2c660 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
2c670 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
2c680 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
2c690 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
2c6a0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
2c6b0 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
2c6c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2c6d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2c6e0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2c6f0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2c700 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2c710 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
2c720 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2c730 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2c740 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2c750 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2c760 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2c770 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
2c780 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2c790 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
2c7a0 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
2c7b0 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44  ameter.** METHOD
2c7c0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2c7d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2c7e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2c7f0 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
2c800 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
2c810 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2c820 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
2c830 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
2c840 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c850 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
2c860 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2c870 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
2c880 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
2c890 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
2c8a0 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
2c8b0 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
2c8c0 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
2c8d0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
2c8e0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2c8f0 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
2c900 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
2c910 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
2c920 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
2c930 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
2c940 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
2c950 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
2c960 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
2c970 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
2c980 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
2c990 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
2c9a0 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
2c9b0 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
2c9c0 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
2c9d0 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
2c9e0 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
2c9f0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2ca00 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
2ca10 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2ca20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
2ca30 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
2ca40 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
2ca50 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
2ca60 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
2ca70 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
2ca80 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2ca90 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
2caa0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
2cab0 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
2cac0 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
2cad0 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
2cae0 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
2caf0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
2cb00 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
2cb10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2cb20 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
2cb30 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2cb40 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2cb50 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2cb60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2cb70 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2cb80 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2cb90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2cba0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
2cbb0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2cbc0 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
2cbd0 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2cbe0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
2cbf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2cc00 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2cc10 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
2cc20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
2cc30 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d   Given Name.** M
2cc40 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2cc50 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  tmt.**.** ^Retur
2cc60 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
2cc70 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
2cc80 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
2cc90 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
2cca0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
2ccb0 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
2ccc0 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
2ccd0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
2cce0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2ccf0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2cd00 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
2cd10 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
2cd20 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
2cd30 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
2cd40 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
2cd50 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
2cd60 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
2cd70 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
2cd80 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
2cd90 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
2cda0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
2cdb0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
2cdc0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2cdd0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2cde0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2cdf0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2ce00 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2ce10 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2ce20 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2ce30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ce40 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a  meter_name()]..*
2ce50 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2ce60 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2ce70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2ce80 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
2ce90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
2cea0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
2ceb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cec0 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
2ced0 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
2cee0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d  d Statement.** M
2cef0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2cf00 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  tmt.**.** ^Contr
2cf10 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
2cf20 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
2cf30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2cf40 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
2cf50 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
2cf60 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
2cf70 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
2cf80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2cf90 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
2cfa0 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
2cfb0 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
2cfc0 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51  s to NULL..*/.SQ
2cfd0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2cfe0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2cff0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2d000 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2d010 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d020 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
2d030 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
2d040 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
2d050 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2d060 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2d070 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2d080 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2d090 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
2d0a0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2d0b0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
2d0c0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
2d0d0 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
2d0e0 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
2d0f0 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
2d100 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
2d110 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
2d120 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
2d130 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2d140 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
2d150 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2d160 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2d170 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2d180 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2d190 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2d1a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2d1b0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
2d1c0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
2d1d0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2d1e0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
2d1f0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2d200 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
2d210 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
2d220 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
2d230 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
2d240 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
2d250 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
2d260 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2d270 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
2d280 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2d290 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
2d2a0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
2d2b0 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
2d2c0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2d2d0 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
2d2e0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2d2f0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
2d300 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2d310 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2d320 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
2d330 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2d340 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
2d350 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
2d360 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
2d370 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2d380 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
2d390 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
2d3a0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
2d3b0 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
2d3c0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2d3d0 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
2d3e0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
2d3f0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
2d400 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2d410 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
2d420 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d430 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2d440 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2d450 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2d460 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2d470 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2d480 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2d490 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2d4a0 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2d4b0 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
2d4c0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2d4d0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
2d4e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2d4f0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
2d500 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
2d510 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
2d520 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
2d530 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
2d540 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
2d550 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
2d560 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
2d570 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
2d580 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
2d590 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
2d5a0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2d5b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2d5c0 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
2d5d0 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
2d5e0 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
2d5f0 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
2d600 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
2d610 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
2d620 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
2d630 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
2d640 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
2d650 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
2d660 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
2d670 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
2d680 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
2d690 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
2d6a0 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ext..*/.SQLITE_A
2d6b0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
2d6c0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2d6d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2d6e0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2d6f0 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f   int N);.SQLITE_
2d700 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2d710 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2d720 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2d730 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2d740 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
2d750 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
2d760 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
2d770 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2d780 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2d790 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2d7a0 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
2d7b0 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
2d7c0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
2d7d0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2d7e0 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
2d7f0 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
2d800 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
2d810 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
2d820 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
2d830 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
2d840 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
2d850 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
2d860 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
2d870 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
2d880 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
2d890 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
2d8a0 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
2d8b0 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
2d8c0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
2d8d0 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
2d8e0 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
2d8f0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
2d900 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
2d910 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
2d920 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
2d930 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
2d940 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2d950 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
2d960 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
2d970 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
2d980 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
2d990 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2d9a0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2d9b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2d9c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2d9d0 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2d9e0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2d9f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2da00 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2da10 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2da20 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
2da30 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
2da40 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
2da50 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
2da60 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
2da70 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
2da80 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
2da90 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
2daa0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
2dab0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2dac0 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
2dad0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2dae0 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
2daf0 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
2db00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2db10 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
2db20 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
2db30 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2db40 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
2db50 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2db60 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
2db70 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
2db80 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
2db90 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
2dba0 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
2dbb0 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
2dbc0 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
2dbd0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
2dbe0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
2dbf0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
2dc00 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
2dc10 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
2dc20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
2dc30 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
2dc40 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
2dc50 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2dc60 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
2dc70 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
2dc80 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
2dc90 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
2dca0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2dcb0 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
2dcc0 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
2dcd0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2dce0 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
2dcf0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2dd00 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
2dd10 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
2dd20 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
2dd30 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
2dd40 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
2dd50 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
2dd60 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
2dd70 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
2dd80 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
2dd90 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
2dda0 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
2ddb0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2ddc0 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
2ddd0 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
2dde0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2ddf0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2de00 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2de10 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2de20 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2de30 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2de40 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
2de50 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2de60 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2de70 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2de80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
2de90 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
2dea0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2deb0 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
2dec0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2ded0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2dee0 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
2def0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
2df00 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2df10 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2df20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2df30 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2df40 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
2df50 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
2df60 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2df70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2df80 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
2df90 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
2dfa0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2dfb0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2dfc0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51  undefined..*/.SQ
2dfd0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2dfe0 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
2dff0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2e000 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2e010 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2e020 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2e030 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
2e040 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2e050 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2e060 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
2e070 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2e080 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2e090 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
2e0a0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2e0b0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
2e0c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2e0d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2e0e0 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
2e0f0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2e100 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2e110 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2e120 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2e130 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
2e140 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2e150 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2e160 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
2e170 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2e180 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2e190 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
2e1a0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
2e1b0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
2e1c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2e1d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e1e0 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
2e1f0 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
2e200 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
2e210 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2e220 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72  .**.** ^(The fir
2e230 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2e240 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2e250 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
2e260 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
2e270 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2e280 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
2e290 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
2e2a0 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
2e2b0 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
2e2c0 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
2e2d0 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
2e2e0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2e2f0 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
2e300 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2e310 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
2e320 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
2e330 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68  urned.)^  ^If th
2e340 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2e350 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
2e360 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
2e370 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
2e380 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
2e390 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2e3a0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2e3b0 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
2e3c0 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
2e3d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
2e3e0 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
2e3f0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
2e400 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
2e410 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
2e420 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
2e430 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
2e440 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
2e450 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
2e460 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
2e470 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
2e480 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
2e490 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
2e4a0 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
2e4b0 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
2e4c0 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
2e4d0 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
2e4e0 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
2e4f0 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
2e500 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a  umn (i==0).)^.**
2e510 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
2e520 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
2e530 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a  e typing.  ^So j
2e540 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
2e550 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
2e560 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
2e570 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
2e580 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
2e590 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
2e5a0 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
2e5b0 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
2e5c0 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
2e5d0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
2e5e0 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
2e5f0 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
2e600 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
2e610 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20  c.  ^Type.** is 
2e620 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2e630 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
2e640 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
2e650 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
2e660 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
2e670 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49   values..*/.SQLI
2e680 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2e690 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
2e6a0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2e6b0 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
2e6c0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2e6d0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2e6e0 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
2e6f0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2e700 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
2e710 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2e720 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e730 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
2e740 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
2e750 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2e760 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  stmt.**.** After
2e770 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2e780 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
2e790 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2e7a0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2e7b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2e7c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2e7d0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2e7e0 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
2e7f0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
2e800 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e810 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2e820 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
2e830 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
2e840 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
2e850 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2e860 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
2e870 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2e880 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
2e890 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2e8a0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2e8b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
2e8c0 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
2e8d0 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
2e8e0 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
2e8f0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
2e900 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
2e910 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2e920 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2e930 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2e940 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
2e950 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2e960 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
2e970 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2e980 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2e990 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
2e9a0 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
2e9b0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2e9c0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
2e9d0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
2e9e0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2e9f0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
2ea00 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
2ea10 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
2ea20 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2ea30 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
2ea40 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
2ea50 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
2ea60 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
2ea70 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
2ea80 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
2ea90 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
2eaa0 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
2eab0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2eac0 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
2ead0 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
2eae0 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
2eaf0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2eb00 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
2eb10 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
2eb20 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2eb30 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
2eb40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2eb50 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
2eb60 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
2eb70 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
2eb80 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
2eb90 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
2eba0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2ebb0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
2ebc0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
2ebd0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
2ebe0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
2ebf0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
2ec00 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
2ec10 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2ec20 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
2ec30 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
2ec40 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
2ec50 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2ec60 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
2ec70 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
2ec80 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
2ec90 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
2eca0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
2ecb0 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
2ecc0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2ecd0 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2ece0 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
2ecf0 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
2ed00 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2ed10 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2ed20 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
2ed30 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
2ed40 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
2ed50 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2ed60 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2ed70 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2ed80 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
2ed90 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
2eda0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
2edb0 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
2edc0 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
2edd0 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
2ede0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
2edf0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
2ee00 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
2ee10 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
2ee20 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
2ee30 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
2ee40 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
2ee50 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
2ee60 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
2ee70 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2ee80 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
2ee90 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
2eea0 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
2eeb0 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
2eec0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
2eed0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
2eee0 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
2eef0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
2ef00 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
2ef10 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
2ef20 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
2ef30 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2ef40 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2ef50 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
2ef60 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
2ef70 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
2ef80 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2ef90 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
2efa0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
2efb0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2efc0 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
2efd0 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
2efe0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
2eff0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
2f000 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
2f010 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
2f020 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
2f030 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
2f040 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
2f050 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2f060 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
2f070 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2f080 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
2f090 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
2f0a0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2f0b0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
2f0c0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
2f0d0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2f0e0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
2f0f0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
2f100 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
2f110 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
2f120 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
2f130 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
2f140 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
2f150 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f160 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
2f170 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
2f180 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
2f190 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
2f1a0 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
2f1b0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
2f1c0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
2f1d0 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
2f1e0 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
2f1f0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
2f200 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
2f210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f220 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
2f230 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
2f240 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
2f250 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
2f260 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
2f270 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
2f280 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
2f290 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
2f2a0 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
2f2b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2f2c0 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
2f2d0 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2f2e0 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
2f2f0 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
2f300 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2f310 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
2f320 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2f330 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
2f340 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
2f350 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
2f360 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2f370 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
2f380 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2f390 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
2f3a0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
2f3b0 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
2f3c0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2f3d0 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
2f3e0 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
2f3f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
2f400 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
2f410 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2f420 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
2f430 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
2f440 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
2f450 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
2f460 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2f470 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
2f480 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
2f490 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
2f4a0 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
2f4b0 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
2f4c0 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
2f4d0 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
2f4e0 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
2f4f0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
2f500 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2f510 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
2f520 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
2f530 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
2f540 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
2f550 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
2f560 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
2f570 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
2f580 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
2f590 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
2f5a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
2f5b0 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
2f5c0 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
2f5d0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
2f5e0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
2f5f0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
2f600 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2f610 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
2f620 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2f630 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
2f640 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f650 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2f660 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
2f670 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
2f680 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
2f690 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2f6a0 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
2f6b0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
2f6c0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
2f6d0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
2f6e0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
2f6f0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
2f700 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
2f710 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2f720 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
2f730 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
2f740 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
2f750 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
2f760 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2f770 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2f780 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2f790 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
2f7a0 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
2f7b0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2f7c0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2f7d0 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
2f7e0 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
2f7f0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
2f800 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
2f810 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2f820 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
2f830 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
2f840 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
2f850 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2f860 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ended..*/.SQLITE
2f870 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2f880 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2f890 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
2f8a0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2f8b0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
2f8c0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
2f8d0 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult set.** METHO
2f8e0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2f8f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2f900 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2f910 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2f920 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2f930 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
2f940 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
2f950 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2f960 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2f970 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2f980 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
2f990 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
2f9a0 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
2f9b0 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
2f9c0 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
2f9d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2f9e0 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
2f9f0 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
2fa00 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
2fa10 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
2fa20 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
2fa30 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
2fa40 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2fa50 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
2fa60 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
2fa70 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2fa80 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2fa90 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2faa0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2fab0 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
2fac0 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
2fad0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2fae0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2faf0 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
2fb00 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2fb10 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
2fb20 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
2fb30 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
2fb40 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2fb50 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
2fb60 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
2fb70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
2fb80 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
2fb90 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
2fba0 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
2fbb0 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
2fbc0 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
2fbd0 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
2fbe0 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
2fbf0 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
2fc00 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
2fc10 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2fc20 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2fc30 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
2fc40 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2fc50 4c 4c 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  LL sqlite3_data_
2fc60 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2fc70 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2fc80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2fc90 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
2fca0 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2fcb0 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
2fcc0 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
2fcd0 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2fce0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2fcf0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2fd00 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2fd10 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2fd20 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2fd30 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2fd40 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2fd50 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2fd60 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2fd70 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2fd80 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
2fd90 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
2fda0 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
2fdb0 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
2fdc0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2fdd0 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
2fde0 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
2fdf0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
2fe00 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
2fe10 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
2fe20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
2fe30 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
2fe40 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
2fe50 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
2fe60 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
2fe70 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
2fe80 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
2fe90 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
2fea0 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
2feb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2fec0 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
2fed0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
2fee0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2fef0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
2ff00 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
2ff10 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
2ff20 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
2ff30 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
2ff40 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2ff50 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2ff60 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2ff70 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2ff80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ff90 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2ffa0 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2ffb0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2ffc0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2ffd0 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  s}.** METHOD: sq
2ffe0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2fff0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
30000 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
30010 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
30020 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
30030 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
30040 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
30050 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
30060 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
30070 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
30080 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
30090 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
300a0 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
300b0 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
300c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
300d0 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
300e0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
300f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
30100 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
30110 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
30120 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
30130 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
30140 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
30150 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
30160 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
30170 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
30180 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
30190 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
301a0 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
301b0 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
301c0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
301d0 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
301e0 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
301f0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
30200 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
30210 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
30220 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
30230 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
30240 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
30250 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
30260 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
30270 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
30280 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
30290 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
302a0 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
302b0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
302c0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
302d0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
302e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
302f0 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
30300 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
30310 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
30320 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
30330 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
30340 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
30350 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
30360 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
30370 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
30380 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
30390 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
303a0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
303b0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
303c0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
303d0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
303e0 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
303f0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
30400 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
30410 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
30420 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
30430 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
30440 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
30450 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
30460 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
30470 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
30480 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
30490 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
304a0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
304b0 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
304c0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
304d0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
304e0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
304f0 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
30500 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
30510 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
30520 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
30530 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
30540 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
30550 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
30560 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
30570 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
30580 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
30590 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
305a0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
305b0 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
305c0 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
305d0 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
305e0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
305f0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
30600 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
30610 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
30620 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
30630 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
30640 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
30650 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
30660 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
30670 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
30680 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
30690 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
306a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
306b0 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
306c0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
306d0 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
306e0 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
306f0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
30700 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
30710 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
30720 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
30730 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
30740 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
30750 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
30760 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
30770 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
30780 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
30790 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
307a0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
307b0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
307c0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
307d0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
307e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
307f0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
30800 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
30810 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
30820 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
30830 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
30840 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
30850 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
30860 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30870 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
30880 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
30890 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
308a0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
308b0 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
308c0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
308d0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
308e0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
308f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
30900 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
30910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30920 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
30930 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
30940 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
30950 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
30960 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
30970 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
30980 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
30990 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
309a0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
309b0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
309c0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
309d0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
309e0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
309f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30a00 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
30a10 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
30a20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
30a30 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
30a40 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
30a50 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
30a60 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
30a70 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
30a80 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
30a90 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
30aa0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
30ab0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
30ac0 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
30ad0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
30ae0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
30af0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
30b00 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
30b10 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
30b20 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
30b30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
30b40 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
30b50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
30b60 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
30b70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30b80 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
30b90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30ba0 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
30bb0 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
30bc0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
30bd0 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
30be0 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
30bf0 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
30c00 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
30c10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
30c20 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
30c30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
30c40 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
30c50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
30c60 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
30c70 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
30c80 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
30c90 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
30ca0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
30cb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30cc0 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
30cd0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
30ce0 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
30cf0 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
30d00 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
30d10 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
30d20 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
30d30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30d40 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
30d50 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
30d60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
30d70 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67  **.** <b>Warning
30d80 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63  :</b> ^The objec
30d90 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
30da0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
30db0 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
30dc0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
30dd0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30de0 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74  ct.  In a multit
30df0 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d  hreaded environm
30e00 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f  ent,.** an unpro
30e10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
30e20 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
30e30 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61 66  only be used saf
30e40 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  ely with.** [sql
30e50 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
30e60 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
30e70 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
30e80 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
30e90 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30ea0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
30eb0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
30ec0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
30ed0 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
30ee0 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
30ef0 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
30f00 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
30f10 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
30f20 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
30f30 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
30f40 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
30f50 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
30f60 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
30f70 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
30f80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
30f90 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
30fa0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
30fb0 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
30fc0 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20  riate.  ^For.** 
30fd0 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
30fe0 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
30ff0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
31000 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
31010 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
31020 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
31030 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
31040 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
31050 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
31060 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
31070 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
31080 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
31090 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
310a0 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
310b0 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
310c0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
310d0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
310e0 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
310f0 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
31100 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
31110 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
31120 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
31130 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
31140 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
31150 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
31160 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
31170 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
31180 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
31190 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
311a0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
311b0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
311c0 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
311d0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
311e0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
311f0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
31200 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
31210 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
31220 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
31230 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
31240 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
31250 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
31260 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
31270 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
31280 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
31290 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
312a0 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
312b0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
312c0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
312d0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
312e0 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
312f0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
31300 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
31310 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
31320 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
31330 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
31340 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
31350 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
31360 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
31370 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
31380 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
31390 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42  <td> [CAST] to B
313a0 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  LOB.** <tr><td> 
313b0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
313c0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
313d0 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
313e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
313f0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
31400 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
31410 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
31420 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
31430 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
31440 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
31450 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
31460 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
31470 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
31480 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
31490 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
314a0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
314b0 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
314c0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
314d0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
314e0 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
314f0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
31500 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
31510 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
31520 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  e>)^.**.** Note 
31530 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
31540 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
31550 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
31560 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
31570 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
31580 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
31590 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
315a0 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
315b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
315c0 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
315d0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
315e0 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
315f0 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
31600 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
31610 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
31620 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
31630 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
31640 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
31650 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
31660 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
31670 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
31680 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
31690 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
316a0 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
316b0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
316c0 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
316d0 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
316e0 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
316f0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
31700 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
31710 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
31720 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31730 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
31740 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
31750 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
31760 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
31770 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
31780 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
31790 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
317a0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
317b0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
317c0 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
317d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
317e0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
317f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
31800 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
31810 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
31820 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
31830 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
31840 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
31850 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
31860 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
31870 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
31880 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
31890 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
318a0 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
318b0 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
318c0 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
318d0 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
318e0 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
318f0 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
31900 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65  ointer reference
31910 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  s will have been
31920 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
31930 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
31940 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
31950 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
31960 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
31970 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68  but sometimes th
31980 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f  ey.** are not po
31990 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
319a0 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
319b0 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
319c0 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  alidated..**.** 
319d0 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63  The safest polic
319e0 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
319f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
31a00 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
31a10 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
31a20 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
31a30 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
31a40 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
31a50 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
31a60 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
31a70 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
31a80 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
31a90 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
31aa0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
31ab0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
31ac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
31ad0 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
31ae0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
31af0 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
31b00 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
31b10 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
31b20 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
31b30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
31b40 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
31b50 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
31b60 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
31b70 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
31b80 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
31b90 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
31ba0 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
31bb0 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
31bc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31bd0 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
31be0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
31bf0 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
31c00 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
31c10 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
31c20 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
31c30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
31c40 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
31c50 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
31c60 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
31c70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
31c80 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
31c90 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
31ca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
31cb0 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
31cc0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
31cd0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
31ce0 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
31cf0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
31d00 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
31d10 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
31d20 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
31d30 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
31d40 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
31d50 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
31d60 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
31d70 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31d80 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
31d90 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
31da0 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
31db0 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
31dc0 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
31dd0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
31de0 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61   <em>not</em> pa
31df0 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
31e00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
31e10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
31e20 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
31e30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
31e40 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
31e50 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
31e60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d  ..**.** ^(If a m
31e70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
31e80 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
31e90 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
31ea0 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
31eb0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
31ec0 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
31ed0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
31ee0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
31ef0 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
31f00 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
31f10 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
31f20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
31f30 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
31f40 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
31f50 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
31f60 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
31f70 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
31f80 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53  E_NOMEM].)^.*/.S
31f90 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
31fa0 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
31fb0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
31fc0 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
31fd0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
31fe0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
31ff0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
32000 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32010 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
32020 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
32030 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
32040 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
32050 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32060 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
32070 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
32080 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65  QLITE_API double
32090 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
320a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
320b0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
320c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
320d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
320e0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
320f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
32100 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
32110 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
32120 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
32130 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41  t64 SQLITE_STDCA
32140 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
32150 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
32160 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
32170 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
32180 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
32190 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
321a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
321b0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
321c0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
321d0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
321e0 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
321f0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
32200 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
32210 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
32220 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
32230 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
32240 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
32250 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
32260 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
32270 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
32280 74 65 33 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54  te3_value *SQLIT
32290 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
322a0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
322b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
322c0 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
322d0 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
322e0 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
322f0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
32300 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c   DESTRUCTOR: sql
32310 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
32320 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
32330 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
32340 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
32350 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
32360 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
32370 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
32380 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
32390 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
323a0 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65  encountered no e
323b0 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74  rrors.** or if t
323c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
323d0 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75  never been evalu
323e0 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ated, then sqlit
323f0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65  e3_finalize() re
32400 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f  turns.** SQLITE_
32410 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73  OK.  ^If the mos
32420 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
32430 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74  ion of statement
32440 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a   S failed, then.
32450 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ** sqlite3_final
32460 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74  ize(S) returns t
32470 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  he appropriate [
32480 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a  error code] or.*
32490 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  * [extended erro
324a0 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
324b0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
324c0 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20  lize(S) routine 
324d0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
324e0 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
324f0 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79  g.** the life cy
32500 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64  cle of [prepared
32510 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a   statement] S:.*
32520 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65  * before stateme
32530 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61  nt S is ever eva
32540 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a  luated, after.**
32550 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c   one or more cal
32560 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
32570 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65  eset()], or afte
32580 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f  r any call.** to
32590 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
325a0 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  ] regardless of 
325b0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
325c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
325d0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
325e0 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ecution..**.** ^
325f0 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  Invoking sqlite3
32600 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61  _finalize() on a
32610 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
32620 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
32630 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  p..**.** The app
32640 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69  lication must fi
32650 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72  nalize every [pr
32660 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32670 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76  ] in order to av
32680 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20  oid.** resource 
32690 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20  leaks.  It is a 
326a0 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66  grievous error f
326b0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
326c0 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65  on to try to use
326d0 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73  .** a prepared s
326e0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
326f0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
32700 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f  ized.  Any use o
32710 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  f a prepared.** 
32720 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
32730 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
32740 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74  lized can result
32750 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
32760 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  d.** undesirable
32770 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61   behavior such a
32780 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20  s segfaults and 
32790 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e  heap corruption.
327a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
327b0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
327c0 4c 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  L sqlite3_finali
327d0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
327e0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
327f0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
32800 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
32810 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d  ment Object.** M
32820 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
32830 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  tmt.**.** The sq
32840 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
32850 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
32860 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
32870 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
32880 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
32890 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
328a0 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
328b0 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
328c0 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
328d0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
328e0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
328f0 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
32900 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
32910 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
32920 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
32930 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
32940 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
32950 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
32960 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
32970 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
32980 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
32990 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
329a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
329b0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
329c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
329d0 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
329e0 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
329f0 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
32a00 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
32a10 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
32a20 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
32a30 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
32a40 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
32a50 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
32a60 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
32a70 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
32a80 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
32a90 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
32aa0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
32ab0 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
32ac0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
32ad0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
32ae0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
32af0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
32b00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
32b10 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
32b20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b30 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
32b40 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
32b50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
32b60 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
32b70 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
32b80 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
32b90 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
32ba0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
32bb0 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
32bc0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
32bd0 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
32be0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
32bf0 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
32c00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32c10 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ] S..*/.SQLITE_A
32c20 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
32c30 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65  DCALL sqlite3_re
32c40 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
32c50 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
32c60 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
32c70 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
32c80 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
32c90 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
32ca0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
32cb0 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
32cc0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
32cd0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
32ce0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
32cf0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
32d00 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
32d10 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
32d20 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
32d30 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
32d40 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
32d50 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
32d60 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
32d70 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
32d80 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
32d90 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
32da0 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
32db0 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
32dc0 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
32dd0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
32de0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
32df0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
32e00 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
32e10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
32e20 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
32e30 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
32e40 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
32e50 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
32e60 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
32e70 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
32e80 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
32e90 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
32ea0 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
32eb0 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
32ec0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
32ed0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
32ee0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
32ef0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
32f00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
32f10 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
32f20 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
32f30 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
32f40 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
32f50 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
32f60 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
32f70 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
32f80 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
32f90 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
32fa0 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
32fb0 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
32fc0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
32fd0 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
32fe0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
32ff0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
33000 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
33010 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
33020 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
33030 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
33040 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
33050 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
33060 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
33070 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
33080 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
33090 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
330a0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
330b0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
330c0 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
330d0 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
330e0 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
330f0 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
33100 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
33110 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
33120 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
33130 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
33140 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
33150 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
33160 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
33170 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
33180 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
33190 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
331a0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
331b0 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
331c0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
331d0 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
331e0 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
331f0 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
33200 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
33210 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
33220 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
33230 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
33240 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
33250 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
33260 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
33270 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
33280 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
33290 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
332a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
332b0 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
332c0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
332d0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
332e0 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
332f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
33300 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
33310 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
33320 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
33330 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
33340 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
33350 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
33360 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
33370 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61  rameters.  The a
33380 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
33390 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d  d set this param
333a0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  eter to.** [SQLI
333b0 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74  TE_UTF16LE] if t
333c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
333d0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
333e0 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  es .** [sqlite3_
333f0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
33400 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
33410 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
33420 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70  E] if the.** imp
33430 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
33440 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  kes [sqlite3_val
33450 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f  ue_text16be()] o
33460 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a  n an input, or.*
33470 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  * [SQLITE_UTF16]
33480 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   if [sqlite3_val
33490 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20  ue_text16()] is 
334a0 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  used, or [SQLITE
334b0 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77  _UTF8].** otherw
334c0 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20  ise.  ^The same 
334d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  SQL function may
334e0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
334f0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73  ultiple times us
33500 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74  ing.** different
33510 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
33520 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20  encodings, with 
33530 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d  different implem
33540 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a  entations for.**
33550 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a   each encoding..
33560 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
33570 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
33580 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
33590 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
335a0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
335b0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
335c0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
335d0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
335e0 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
335f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
33600 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
33610 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   may optionally 
33620 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51  be ORed with [SQ
33630 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
33640 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  IC].** to signal
33650 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69   that the functi
33660 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  on will always r
33670 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72  eturn the same r
33680 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74  esult given.** t
33690 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77  he same inputs w
336a0 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53  ithin a single S
336b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d  QL statement.  M
336c0 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ost SQL function
336d0 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69  s are.** determi
336e0 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69  nistic.  The bui
336f0 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d  lt-in [random()]
33700 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
33710 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61   an example of a
33720 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  .** function tha
33730 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69  t is not determi
33740 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c  nistic.  The SQL
33750 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  ite query planne
33760 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20  r is able to.** 
33770 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e  perform addition
33780 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  al optimizations
33790 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69   on deterministi
337a0 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20  c functions, so 
337b0 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  use.** of the [S
337c0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
337d0 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63  TIC] flag is rec
337e0 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70  ommended where p
337f0 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ossible..**.** ^
33800 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
33810 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
33820 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
33830 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
33840 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
33850 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
33860 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
33870 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
33880 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
33890 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
338a0 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
338b0 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
338c0 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
338d0 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
338e0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
338f0 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
33900 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
33910 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
33920 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
33930 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
33940 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
33950 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
33960 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
33970 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
33980 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
33990 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
339a0 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
339b0 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
339c0 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
339d0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
339e0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
339f0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
33a00 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
33a10 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
33a20 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
33a30 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
33a40 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
33a50 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
33a60 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
33a70 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
33a80 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20  LL pointers for 
33a90 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
33aa0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
33ab0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
33ac0 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  ninth parameter 
33ad0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
33ae0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
33af0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
33b00 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
33b10 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
33b20 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
33b30 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
33b40 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
33b50 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
33b60 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
33b70 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
33b80 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
33b90 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
33ba0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33bb0 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
33bc0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
33bd0 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
33be0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
33bf0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33c00 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
33c10 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
33c20 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
33c30 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
33c40 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
33c50 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
33c60 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
33c70 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
33c80 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
33c90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
33ca0 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
33cb0 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
33cc0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
33cd0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33ce0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
33cf0 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
33d00 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
33d10 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
33d20 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
33d30 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
33d40 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
33d50 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
33d60 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
33d70 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
33d80 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
33d90 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
33da0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
33db0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
33dc0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
33dd0 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
33de0 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
33df0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
33e00 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
33e10 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
33e20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
33e30 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
33e40 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
33e50 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
33e60 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
33e70 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
33e80 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
33e90 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
33ea0 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
33eb0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
33ec0 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
33ed0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
33ee0 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
33ef0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
33f00 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
33f10 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
33f20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
33f30 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
33f40 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
33f50 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
33f60 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
33f70 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
33f80 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
33f90 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
33fa0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
33fb0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
33fc0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
33fd0 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
33fe0 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
33ff0 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
34000 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
34010 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
34020 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
34030 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
34040 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
34050 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34060 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
34070 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
34080 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
34090 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
340a0 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
340b0 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
340c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
340d0 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
340e0 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
340f0 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
34100 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
34110 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
34120 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
34130 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
34140 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
34150 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
34160 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
34170 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
34180 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
34190 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
341a0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
341b0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
341c0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
341d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
341e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
341f0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
34200 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
34210 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
34220 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
34230 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
34240 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53  3_context*).);.S
34250 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
34260 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
34270 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34280 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
34290 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
342a0 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
342b0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
342c0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
342d0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
342e0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
342f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
34300 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
34310 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
34320 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
34330 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
34340 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
34350 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
34360 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
34370 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
34380 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
34390 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
343a0 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
343b0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
343c0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
343d0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
343e0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
343f0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
34400 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
34410 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
34420 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
34430 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
34440 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
34450 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
34460 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
34470 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
34480 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34490 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
344a0 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
344b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
344c0 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
344d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
344e0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
344f0 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
34500 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
34510 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
34520 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
34530 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
34540 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
34550 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20  F8           1  
34560 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31    /* IMP: R-3751
34570 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69  4-35566 */.#defi
34580 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
34590 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a  E        2    /*
345a0 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37   IMP: R-03371-37
345b0 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  637 */.#define S
345c0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
345d0 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50       3    /* IMP
345e0 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20  : R-51971-34154 
345f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
34600 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
34610 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
34620 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
34630 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
34640 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
34650 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74  5    /* Deprecat
34660 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
34670 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
34680 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
34690 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
346a0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
346b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
346c0 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a  nction Flags.**.
346d0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
346e0 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74  ts may be ORed t
346f0 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65  ogether with the
34700 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
34710 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65  8 | preferred te
34720 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20  xt encoding] as 
34730 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
34740 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ent.** to [sqlit
34750 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34760 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
34770 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
34780 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34790 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
347a0 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23  tion_v2()]..*/.#
347b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
347c0 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30  TERMINISTIC    0
347d0 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x800../*.** CAPI
347e0 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
347f0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
34800 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
34810 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
34820 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
34830 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
34840 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
34850 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
34860 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
34870 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
34880 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
34890 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
348a0 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
348b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
348c0 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
348d0 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
348e0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f  ctions.  To enco
348f0 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72  urage programmer
34900 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68  s to avoid.** th
34910 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
34920 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61  e will not expla
34930 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  in what they do.
34940 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
34950 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
34960 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  ED.SQLITE_API SQ
34970 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
34980 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
34990 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  LL sqlite3_aggre
349a0 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
349b0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
349c0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
349d0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53  DEPRECATED int S
349e0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
349f0 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
34a00 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
34a10 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
34a20 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53  DEPRECATED int S
34a30 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
34a40 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
34a50 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
34a60 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
34a70 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
34a80 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
34a90 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  TED int SQLITE_S
34aa0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67  TDCALL sqlite3_g
34ab0 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
34ac0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
34ad0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
34ae0 44 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  D void SQLITE_ST
34af0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 68  DCALL sqlite3_th
34b00 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
34b10 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  d);.SQLITE_API S
34b20 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
34b30 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
34b40 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ALL sqlite3_memo
34b50 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
34b60 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
34b70 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20  nt64,int),.     
34b80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34b90 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69   void*,sqlite3_i
34ba0 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
34bb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
34bc0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c  btaining SQL Val
34bd0 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
34be0 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
34bf0 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
34c00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
34c10 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
34c20 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
34c30 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
34c40 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
34c50 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
34c60 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
34c70 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
34c80 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
34c90 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20  regate.  .**.** 
34ca0 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
34cb0 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
34cc0 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
34cd0 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
34ce0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
34cf0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34d00 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
34d10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34d20 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
34d30 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
34d40 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
34d50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
34d60 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
34d70 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65  * The 3rd parame
34d80 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
34d90 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
34da0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
34db0 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
34dc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
34dd0 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
34de0 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
34df0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
34e00 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
34e10 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
34e20 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
34e30 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
34e40 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
34e50 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
34e60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
34e70 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
34e80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
34e90 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
34ea0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
34eb0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
34ec0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
34ed0 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
34ee0 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
34ef0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
34f00 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
34f10 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
34f20 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
34f30 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
34f40 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
34f50 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
34f60 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
34f70 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
34f80 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 74  ** except that t
34f90 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
34fa0 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
34fb0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
34fc0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
34fd0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
34fe0 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
34ff0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
35000 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
35010 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
35020 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
35030 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
35040 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
35050 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
35060 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
35070 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
35080 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
35090 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
350a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
350b0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
350c0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
350d0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
350e0 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
350f0 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
35100 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
35110 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
35120 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
35130 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
35140 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
35150 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
35160 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
35170 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
35180 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
35190 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
351a0 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
351b0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
351c0 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
351d0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
351e0 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
351f0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
35200 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
35210 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
35220 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
35230 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
35240 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
35250 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
35260 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
35270 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
35280 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
35290 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
352a0 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
352b0 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
352c0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
352d0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
352e0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
352f0 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
35300 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
35310 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
35320 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
35330 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
35340 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
35350 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
35360 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
35370 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
35380 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
35390 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
353a0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
353b0 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
353c0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
353d0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
353e0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
353f0 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
35400 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
35410 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
35420 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
35430 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
35440 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
35450 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
35460 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
35470 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
35480 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
35490 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
354a0 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
354b0 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  rs..*/.SQLITE_AP
354c0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
354d0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
354e0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
354f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
35500 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
35510 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
35520 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
35530 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
35540 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
35550 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
35560 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
35570 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
35580 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
35590 41 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54  API double SQLIT
355a0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
355b0 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
355c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
355d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
355e0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
355f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
35600 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
35610 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
35620 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45  te3_int64 SQLITE
35630 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
35640 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
35650 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
35660 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75  LITE_API const u
35670 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51  nsigned char *SQ
35680 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
35690 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
356a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
356b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
356c0 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  t void *SQLITE_S
356d0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
356e0 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
356f0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
35700 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
35710 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
35720 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
35730 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
35740 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
35750 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
35760 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
35770 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
35780 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
35790 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
357a0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
357b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
357c0 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
357d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
357e0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
357f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
35800 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
35810 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
35820 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
35830 33 52 45 46 3a 20 46 69 6e 64 69 6e 67 20 54 68  3REF: Finding Th
35840 65 20 53 75 62 74 79 70 65 20 4f 66 20 53 51 4c  e Subtype Of SQL
35850 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f   Values.** METHO
35860 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  D: sqlite3_value
35870 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
35880 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65  e3_value_subtype
35890 28 56 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  (V) function ret
358a0 75 72 6e 73 20 74 68 65 20 73 75 62 74 79 70 65  urns the subtype
358b0 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c   for.** an [appl
358c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
358d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72  SQL function] ar
358e0 67 75 6d 65 6e 74 20 56 2e 20 20 54 68 65 20 73  gument V.  The s
358f0 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d  ubtype.** inform
35900 61 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ation can be use
35910 64 20 74 6f 20 70 61 73 73 20 61 20 6c 69 6d 69  d to pass a limi
35920 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  ted amount of co
35930 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  ntext from.** on
35940 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
35950 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55 73 65 20  o another.  Use 
35960 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
35970 75 6c 74 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a  ult_subtype()].*
35980 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 73 65 74  * routine to set
35990 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72   the subtype for
359a0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
359b0 65 20 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e 63  e of an SQL func
359c0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
359d0 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20  te makes no use 
359e0 6f 66 20 73 75 62 74 79 70 65 20 69 74 73 65 6c  of subtype itsel
359f0 66 2e 20 20 49 74 20 6d 65 72 65 6c 79 20 70 61  f.  It merely pa
35a00 73 73 65 73 20 74 68 65 20 73 75 62 74 79 70 65  sses the subtype
35a10 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72 65 73  .** from the res
35a20 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c  ult of one [appl
35a30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35a40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e  SQL function] in
35a50 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20  to the.** input 
35a60 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 53  of another..*/.S
35a70 51 4c 49 54 45 5f 41 50 49 20 75 6e 73 69 67 6e  QLITE_API unsign
35a80 65 64 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  ed int SQLITE_ST
35a90 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
35aa0 6c 75 65 5f 73 75 62 74 79 70 65 28 73 71 6c 69  lue_subtype(sqli
35ab0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
35ac0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
35ad0 70 79 20 41 6e 64 20 46 72 65 65 20 53 51 4c 20  py And Free SQL 
35ae0 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  Values.** METHOD
35af0 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a  : sqlite3_value.
35b00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35b10 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20  e3_value_dup(V) 
35b20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
35b30 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
35b40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
35b50 20 6f 62 6a 65 63 74 20 44 20 61 6e 64 20 72 65   object D and re
35b60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
35b70 74 6f 20 74 68 61 74 20 63 6f 70 79 2e 20 20 5e  to that copy.  ^
35b80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
35b90 75 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ue] returned.** 
35ba0 69 73 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20  is a [protected 
35bb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
35bc0 62 6a 65 63 74 20 65 76 65 6e 20 69 66 20 74 68  bject even if th
35bd0 65 20 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a  e input is not..
35be0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35bf0 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74  value_dup(V) int
35c00 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e  erface returns N
35c10 55 4c 4c 20 69 66 20 56 20 69 73 20 4e 55 4c 4c  ULL if V is NULL
35c20 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f   or if a.** memo
35c30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
35c40 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ils..**.** ^The 
35c50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72  sqlite3_value_fr
35c60 65 65 28 56 29 20 69 6e 74 65 72 66 61 63 65 20  ee(V) interface 
35c70 66 72 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 65  frees an [sqlite
35c80 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
35c90 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
35ca0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
35cb0 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29  ite3_value_dup()
35cc0 5d 2e 20 20 5e 49 66 20 56 20 69 73 20 61 20 4e  ].  ^If V is a N
35cd0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
35ce0 68 65 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  hen sqlite3_valu
35cf0 65 5f 66 72 65 65 28 56 29 20 69 73 20 61 20 68  e_free(V) is a h
35d00 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
35d10 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
35d20 69 74 65 33 5f 76 61 6c 75 65 20 2a 53 51 4c 49  ite3_value *SQLI
35d30 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
35d40 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e  e3_value_dup(con
35d50 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
35d60 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
35d70 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
35d80 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
35d90 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61  _free(sqlite3_va
35da0 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
35db0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
35dc0 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
35dd0 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54  n Context.** MET
35de0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
35df0 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65  text.**.** Imple
35e00 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67  mentations of ag
35e10 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
35e20 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a  tions use this.*
35e30 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  * routine to all
35e40 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72  ocate memory for
35e50 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
35e60 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tate..**.** ^The
35e70 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
35e80 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
35e90 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
35ea0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
35eb0 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69   .** for a parti
35ec0 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20  cular aggregate 
35ed0 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65  function, SQLite
35ee0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20  .** allocates N 
35ef0 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65  of memory, zeroe
35f00 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72  s out that memor
35f10 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
35f20 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
35f30 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e  he new memory. ^
35f40 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  On second and su
35f50 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
35f60 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67  o.** sqlite3_agg
35f70 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
35f80 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67   for the same ag
35f90 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
35fa0 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68   instance,.** th
35fb0 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
35fc0 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69   returned.  Sqli
35fd0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
35fe0 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61  ntext() is norma
35ff0 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e  lly.** called on
36000 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f  ce for each invo
36010 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53  cation of the xS
36020 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64  tep callback and
36030 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73   then one.** las
36040 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  t time when the 
36050 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
36060 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57  is invoked.  ^(W
36070 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63  hen no rows matc
36080 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74  h.** an aggregat
36090 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74  e query, the xSt
360a0 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ep() callback of
360b0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66   the aggregate f
360c0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65  unction.** imple
360d0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76  mentation is nev
360e0 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46  er called and xF
360f0 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64  inal() is called
36100 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a   exactly once..*
36110 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73  * In those cases
36120 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  , sqlite3_aggreg
36130 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69  ate_context() mi
36140 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f  ght be called fo
36150 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  r the.** first t
36160 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  ime from within 
36170 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a  xFinal().)^.**.*
36180 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61  * ^The sqlite3_a
36190 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
361a0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65  (C,N) routine re
361b0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
361c0 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69  nter .** when fi
361d0 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20  rst called if N 
361e0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  is less than or 
361f0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
36200 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20   if a memory.** 
36210 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f  allocate error o
36220 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ccurs..**.** ^(T
36230 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61  he amount of spa
36240 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ce allocated by 
36250 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
36260 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69  e_context(C,N) i
36270 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20  s.** determined 
36280 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  by the N paramet
36290 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63  er on first succ
362a0 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68  essful call.  Ch
362b0 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61  anging the.** va
362c0 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73  lue of N in subs
362d0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
362e0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
362f0 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69  _context() withi
36300 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67  n.** the same ag
36310 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
36320 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e   instance will n
36330 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65  ot resize the me
36340 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
36350 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68  on.)^  Within th
36360 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
36370 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61  k, it is customa
36380 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30  ry to set.** N=0
36390 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c   in calls to sql
363a0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
363b0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74  ontext(C,N) so t
363c0 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74  hat no .** point
363d0 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  less memory allo
363e0 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a  cations occur..*
363f0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
36400 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
36410 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
36420 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
36430 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
36440 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
36450 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
36460 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
36470 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
36480 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
36490 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
364a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
364b0 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
364c0 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
364d0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
364e0 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
364f0 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
36500 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
36510 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
36520 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
36530 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
36540 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
36550 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
36560 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
36570 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
36580 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
36590 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
365a0 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
365b0 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  PI void *SQLITE_
365c0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
365d0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
365e0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
365f0 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
36600 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36610 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
36620 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  Functions.** MET
36630 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
36640 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  text.**.** ^The 
36650 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
36660 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
36670 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
36680 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
36690 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
366a0 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
366b0 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
366c0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
366d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
366e0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
366f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36700 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
36710 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
36720 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
36730 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
36740 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
36750 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
36760 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
36770 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
36780 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
36790 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
367a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
367b0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
367c0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
367d0 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49  E_API void *SQLI
367e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
367f0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
36800 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
36810 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36820 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
36830 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
36840 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
36850 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
36860 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36870 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
36880 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
36890 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
368a0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
368b0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
368c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
368d0 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
368e0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
368f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
36900 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
36910 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
36920 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
36930 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
36940 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
36950 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
36960 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
36970 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
36980 50 49 20 73 71 6c 69 74 65 33 20 2a 53 51 4c 49  PI sqlite3 *SQLI
36990 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
369a0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
369b0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
369c0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
369d0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
369e0 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
369f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
36a00 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
36a10 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
36a20 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
36a30 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29   (non-aggregate)
36a40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
36a50 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
36a60 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
36a70 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
36a80 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
36a90 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
36aa0 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
36ab0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
36ac0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
36ad0 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
36ae0 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
36af0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
36b00 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
36b10 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
36b20 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20   preserved.  An 
36b30 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68  example.** of wh
36b40 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62  ere this might b
36b50 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61  e useful is in a
36b60 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
36b70 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20  ion matching.** 
36b80 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
36b90 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
36ba0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
36bb0 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
36bc0 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
36bd0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
36be0 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72   with the patter
36bf0 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54  n string.  .** T
36c00 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  hen as long as t
36c10 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
36c20 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61  g remains the sa
36c30 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69  me,.** the compi
36c40 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
36c50 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
36c60 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
36c70 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
36c80 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
36c90 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
36ca0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
36cb0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
36cc0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
36cd0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
36ce0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
36cf0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
36d00 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
36d10 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
36d20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
36d30 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
36d40 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36d50 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74   function. ^If t
36d60 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64  here is no metad
36d70 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
36d80 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74  d with the funct
36d90 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68  ion argument, th
36da0 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  is sqlite3_get_a
36db0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
36dc0 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ce.** returns a 
36dd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
36de0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36df0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
36e00 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20  ,P,X) interface 
36e10 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64  saves P as metad
36e20 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
36e30 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
36e40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
36e50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
36e60 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a  .  ^Subsequent.*
36e70 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
36e80 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43  e3_get_auxdata(C
36e90 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f  ,N) return P fro
36ea0 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  m the most recen
36eb0 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  t.** sqlite3_set
36ec0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
36ed0 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65  ) call if the me
36ee0 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20  tadata is still 
36ef0 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c  valid or.** NULL
36f00 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
36f10 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72   has been discar
36f20 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65  ded..** ^After e
36f30 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
36f40 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
36f50 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58  C,N,P,X) where X
36f60 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
36f70 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
36f80 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
36f90 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69  or function X wi
36fa0 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65  th parameter P e
36fb0 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20  xactly.** once, 
36fc0 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74  when the metadat
36fd0 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a  a is discarded..
36fe0 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
36ff0 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65  e to discard the
37000 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79   metadata at any
37010 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67   time, including
37020 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77  : <ul>.** <li> w
37030 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
37040 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
37050 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
37060 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  , or.** <li> whe
37070 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
37080 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
37090 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
370a0 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
370b0 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
370c0 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ent, or.** <li> 
370d0 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74  when sqlite3_set
370e0 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e  _auxdata() is in
370f0 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  voked again on t
37100 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65  he same paramete
37110 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75  r, or.** <li> du
37120 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ring the origina
37130 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  l sqlite3_set_au
37140 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65  xdata() call whe
37150 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20  n a memory .**  
37160 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65      allocation e
37170 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75  rror occurs. </u
37180 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  l>)^.**.** Note 
37190 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20  the last bullet 
371a0 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20  in particular.  
371b0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58  The destructor X
371c0 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   in .** sqlite3_
371d0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
371e0 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61  P,X) might be ca
371f0 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  lled immediately
37200 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20  , before the.** 
37210 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
37220 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
37230 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48  even returns.  H
37240 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ence sqlite3_set
37250 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68  _auxdata().** sh
37260 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e  ould be called n
37270 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ear the end of t
37280 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
37290 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74  ementation and t
372a0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  he.** function i
372b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
372c0 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e  ould not make an
372d0 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72  y use of P after
372e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
372f0 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65  auxdata() has be
37300 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a  en called..**.**
37310 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
37320 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
37330 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
37340 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
37350 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
37360 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
37370 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f   compile-time co
37380 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69  nstants, includi
37390 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  ng literal.** va
373a0 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
373b0 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73  ters] and expres
373c0 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66  sions composed f
373d0 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a  rom the same.)^.
373e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
373f0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
37400 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
37410 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
37420 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
37430 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
37440 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
37450 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
37460 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 65 74  CALL sqlite3_get
37470 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
37480 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
37490 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
374a0 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  id SQLITE_STDCAL
374b0 4c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  L sqlite3_set_au
374c0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
374d0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
374e0 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
374f0 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
37500 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
37510 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
37520 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
37530 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
37540 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
37550 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
37560 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
37570 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
37580 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
37590 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
375a0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
375b0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
375c0 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63   ^If the destruc
375d0 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
375e0 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
375f0 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
37600 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
37610 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
37620 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
37630 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
37640 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
37650 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54  e destroyed.  ^T
37660 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
37670 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
37680 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
37690 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
376a0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
376b0 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
376c0 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
376d0 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
376e0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
376f0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
37700 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
37710 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
37720 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
37730 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
37740 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
37750 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
37760 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  lers..*/.typedef
37770 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
37780 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
37790 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
377a0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
377b0 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
377c0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
377d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
377e0 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
377f0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
37800 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
37810 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
37820 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
37830 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
37840 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
37850 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
37860 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
37870 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
37880 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
37890 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
378a0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
378b0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
378c0 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
378d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
378e0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
378f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
37900 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
37910 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
37920 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
37930 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
37940 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
37950 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70  much like the [p
37960 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
37970 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66  ] family of.** f
37980 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f  unctions used to
37990 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
379a0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
379b0 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
379c0 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
379d0 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72   to the [SQL par
379e0 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74  ameter] document
379f0 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
37a00 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
37a10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37a20 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
37a30 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
37a40 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
37a50 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
37a60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
37a70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
37a80 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
37a90 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
37aa0 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
37ab0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
37ac0 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
37ad0 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
37ae0 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
37af0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
37b00 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37b10 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 20  t_zeroblob(C,N) 
37b20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
37b30 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 43 2c  lt_zeroblob64(C,
37b40 4e 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  N).** interfaces
37b50 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
37b60 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
37b70 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
37b80 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 42  ion to be.** a B
37b90 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
37ba0 6c 6c 20 7a 65 72 6f 20 62 79 74 65 73 20 61 6e  ll zero bytes an
37bb0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
37bc0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e..**.** ^The sq
37bd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
37be0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
37bf0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
37c00 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
37c10 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37c20 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
37c30 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
37c40 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
37c50 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
37c60 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
37c70 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37c80 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
37c90 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37ca0 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
37cb0 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
37cc0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
37cd0 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
37ce0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
37cf0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
37d00 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
37d10 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
37d20 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
37d30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37d40 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
37d50 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
37d60 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
37d70 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
37d80 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
37d90 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
37da0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
37db0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
37dc0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
37dd0 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
37de0 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
37df0 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
37e00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37e10 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
37e20 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
37e30 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
37e40 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
37e50 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
37e60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
37e70 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
37e80 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
37e90 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
37ea0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
37eb0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
37ec0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
37ed0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
37ee0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
37ef0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
37f00 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
37f10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37f20 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
37f30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37f40 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
37f50 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
37f60 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
37f70 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
37f80 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
37f90 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
37fa0 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
37fb0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
37fc0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37fd0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
37fe0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37ff0 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
38000 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
38010 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
38020 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
38030 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
38040 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
38050 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
38060 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
38070 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
38080 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
38090 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
380a0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
380b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
380c0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
380d0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
380e0 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
380f0 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
38100 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
38110 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
38120 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
38130 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
38140 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
38150 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
38160 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
38170 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
38180 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
38190 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
381a0 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
381b0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
381c0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
381d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
381e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
381f0 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63  oobig() interfac
38200 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
38210 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65  to throw an.** e
38220 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
38230 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
38240 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e   BLOB is too lon
38250 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a  g to represent..
38260 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
38270 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
38280 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
38290 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
382a0 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65  to throw an.** e
382b0 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
382c0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
382d0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
382e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
382f0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
38300 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
38310 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
38320 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
38330 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
38340 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
38350 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
38360 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
38370 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
38380 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
38390 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
383a0 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
383b0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
383c0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
383d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
383e0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
383f0 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
38400 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
38410 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
38420 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
38430 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
38440 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38450 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
38460 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
38470 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
38480 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
38490 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
384a0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
384b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
384c0 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
384d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
384e0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
384f0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
38500 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
38510 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
38520 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
38530 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
38540 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
38550 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
38560 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
38570 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
38580 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
38590 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
385a0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
385b0 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
385c0 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
385d0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
385e0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
385f0 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ely..** ^The sql
38600 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
38610 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
38620 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
38630 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70  alue of an.** ap
38640 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
38650 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
38660 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 69   a text string i
38670 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  n an encoding.**
38680 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
38690 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73  e fifth (and las
386a0 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68  t) parameter, wh
386b0 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a  ich must be one.
386c0 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ** of [SQLITE_UT
386d0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
386e0 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  16], [SQLITE_UTF
386f0 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
38700 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e  E_UTF16LE]..** ^
38710 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
38720 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
38730 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
38740 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
38750 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
38760 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
38770 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
38780 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
38790 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
387a0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
387b0 6c 74 5f 74 65 7