System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 47ecccc8a702f88bfce87707104627f4418d39fc:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 33 2e 38 2e 31 31 22 0a 23 64       "3.8.11".#d
10b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
10c0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 38  SION_NUMBER 3008
10d0: 30 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  011.#define SQLI
10e0: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20  TE_SOURCE_ID    
10f0: 20 20 22 32 30 31 35 2d 30 37 2d 32 34 20 32 33    "2015-07-24 23
1100: 3a 32 38 3a 30 35 20 64 62 31 32 39 31 34 39 38  :28:05 db1291498
1110: 31 32 63 62 34 65 61 64 62 34 63 64 37 39 61 64  12cb4eadb4cd79ad
1120: 32 39 33 64 31 34 39 36 32 64 32 36 33 38 64 22  293d14962d2638d"
1130: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1140: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
1150: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
1160: 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
1170: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c  sqlite3_version,
1180: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
1190: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
11a0: 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65  terfaces provide
11b0: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
11c0: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51  ation as the [SQ
11d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a  LITE_VERSION],.*
11e0: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
11f0: 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b  N_NUMBER], and [
1200: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1210: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1220: 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61   macros.** but a
1230: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  re associated wi
1240: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
1250: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
1260: 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61  ader file.  ^(Ca
1270: 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61  utious.** progra
1280: 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c  mmers might incl
1290: 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61  ude assert() sta
12a0: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72  tements in their
12b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
12c0: 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76  ** verify that v
12d0: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
12e0: 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  y these interfac
12f0: 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63  es match the mac
1300: 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65  ros in.** the he
1310: 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 69  ader, and thus i
1320: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
1330: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a  pplication is.**
1340: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1350: 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20  atching library 
1360: 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73  and header files
1370: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  ..**.** <blockqu
1380: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73  ote><pre>.** ass
1390: 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62  ert( sqlite3_lib
13a0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
13b0: 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ==SQLITE_VERSION
13c0: 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73  _NUMBER );.** as
13d0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
13e0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c  ite3_sourceid(),
13f0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1400: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1410: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1420: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1430: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1440: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1450: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1460: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1470: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1480: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
1490: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
14a0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
14b0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
14c0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14d0: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
14e0: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
14f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1500: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1510: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1520: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1530: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1540: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1550: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
1560: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
1570: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
1580: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
1590: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
15a0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
15b0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
15c0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
15d0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
15e0: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
15f0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1600: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1610: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1620: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  BER].  ^The sqli
1630: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66  te3_sourceid() f
1640: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1650: 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
1660: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61   a string consta
1670: 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69  nt whose value i
1680: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68  s the same as th
1690: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  e .** [SQLITE_SO
16a0: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
16b0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a  ocessor macro..*
16c0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
16d0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
16e0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
16f0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
1700: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1710: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
1720: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
1730: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49  on[];.SQLITE_API
1740: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1750: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1760: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76  te3_libversion(v
1770: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
1780: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1790: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
17a0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69  te3_sourceid(voi
17b0: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
17c0: 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
17d0: 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  L sqlite3_libver
17e0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
17f0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1800: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
1810: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
1820: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1830: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1840: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1850: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1860: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
1870: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
1880: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
1890: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
18a0: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
18b0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
18c0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
18d0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
18e0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
18f0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
1900: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
1910: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
1920: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1930: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1940: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1950: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1960: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
1970: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
1980: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
1990: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
19a0: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
19b0: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
19c0: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
19d0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
19e0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
19f0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
1a00: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1a10: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
1a20: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1a30: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1a40: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1a50: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1a60: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1a70: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1a80: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
1a90: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
1aa0: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
1ab0: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
1ac0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1ad0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
1ae0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1af0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
1b00: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
1b10: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
1b20: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1b30: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1b40: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1b50: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1b60: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1b70: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1b80: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1b90: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1ba0: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1bb0: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1bc0: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1bd0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1be0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1bf0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1c00: 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49  DIAGS.SQLITE_API
1c10: 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1c20: 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ALL sqlite3_comp
1c30: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63  ileoption_used(c
1c40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e  onst char *zOptN
1c50: 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ame);.SQLITE_API
1c60: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1c70: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1c80: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1c90: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1ca0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1cb0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1cc0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1cd0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1ce0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1cf0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1d00: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1d10: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1d20: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1d30: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1d40: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1d50: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1d60: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1d70: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1d80: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1d90: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1da0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1db0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1dc0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1dd0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1de0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1df0: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1e00: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1e10: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1e20: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1e30: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1e40: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1e50: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e60: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1e70: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1e80: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1e90: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1ea0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1eb0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1ec0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1ed0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1ee0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1ef0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1f00: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1f10: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1f20: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1f30: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1f40: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1f50: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1f60: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1f70: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1f80: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1f90: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1fa0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1fb0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1fc0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1fd0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
1fe0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
1ff0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2000: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
2010: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
2020: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
2030: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
2040: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
2050: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
2060: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
2070: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
2080: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
2090: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
20a0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
20b0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
20c0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
20d0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
20e0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
20f0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2100: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2110: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2120: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2130: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2140: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2150: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2160: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
2170: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
2180: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
2190: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
21a0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
21b0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
21c0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
21d0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
21e0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
21f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2200: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2210: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2220: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
2230: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
2240: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
2250: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2260: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2270: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2280: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2290: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
22a0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
22b0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
22c0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
22d0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
22e0: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
22f0: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2300: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
2310: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2320: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
2330: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
2340: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2350: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
2360: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2370: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2380: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2390: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23a0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
23b0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
23c0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
23d0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
23e0: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
23f0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
2400: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
2410: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2420: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
2430: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
2440: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
2450: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
2460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
2470: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
2480: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
2490: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
24a0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
24b0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
24c0: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
24d0: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
24e0: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
24f0: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
2500: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2510: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
2520: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
2530: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
2540: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
2550: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
2560: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
2570: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2580: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20  close_v2()] are 
2590: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e  its destructors.
25a0: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
25b0: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
25c0: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
25d0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25e0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
25f0: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2600: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
2610: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
2620: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
2630: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
2640: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
2650: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
2660: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
2670: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
2680: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
2690: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
26a0: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b  teger Types.** K
26b0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
26c0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
26d0: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
26e0: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
26f0: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
2700: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
2710: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
2720: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
2730: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
2740: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
2750: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
2760: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
2770: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
2780: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
2790: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
27a0: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
27b0: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
27c0: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
27d0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
27e0: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
27f0: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
2800: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
2810: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
2820: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79   sqlite_int64 ty
2840: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
2850: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  teger values.** 
2860: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
2870: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
2880: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
2890: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e  75807 inclusive.
28a0: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
28b0: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  3_uint64 and sql
28c0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
28d0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
28e0: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65  er values .** be
28f0: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34  tween 0 and +184
2900: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31  4674407370955161
2910: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a  5 inclusive..*/.
2920: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
2930: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
2940: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2950: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
2960: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2970: 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54  igned SQLITE_INT
2980: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
2990: 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66  int64;.#elif def
29a0: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c  ined(_MSC_VER) |
29b0: 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c  | defined(__BORL
29c0: 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65  ANDC__).  typede
29d0: 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  f __int64 sqlite
29e0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
29f0: 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74  f unsigned __int
2a00: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2a10: 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65  ;.#else.  typede
2a20: 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  f long long int 
2a30: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
2a40: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
2a50: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
2a60: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2a70: 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c  ndif.typedef sql
2a80: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
2a90: 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66  3_int64;.typedef
2aa0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73   sqlite_uint64 s
2ab0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a  qlite3_uint64;..
2ac0: 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69  /*.** If compili
2ad0: 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73  ng for a process
2ae0: 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c  or that lacks fl
2af0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70  oating point sup
2b00: 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74  port,.** substit
2b10: 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20  ute integer for 
2b20: 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a  floating-point..
2b30: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
2b40: 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50  _OMIT_FLOATING_P
2b50: 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f  OINT.# define do
2b60: 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  uble sqlite3_int
2b70: 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  64.#endif../*.**
2b80: 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69   CAPI3REF: Closi
2b90: 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  ng A Database Co
2ba0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 54  nnection.** DEST
2bb0: 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a  RUCTOR: sqlite3.
2bc0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2bd0: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73  e3_close() and s
2be0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2bf0: 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  ) routines are d
2c00: 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f  estructors.** fo
2c10: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  r the [sqlite3] 
2c20: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c  object..** ^Call
2c30: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f  s to sqlite3_clo
2c40: 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  se() and sqlite3
2c50: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75  _close_v2() retu
2c60: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  rn [SQLITE_OK] i
2c70: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  f.** the [sqlite
2c80: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63  3] object is suc
2c90: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f  cessfully destro
2ca0: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f  yed and all asso
2cb0: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72  ciated.** resour
2cc0: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
2cd0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ted..**.** ^If t
2ce0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2cf0: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69  ection is associ
2d00: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61  ated with unfina
2d10: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a  lized prepared.*
2d20: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20  * statements or 
2d30: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
2d40: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74  e3_backup object
2d50: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  s then sqlite3_c
2d60: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c  lose().** will l
2d70: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73  eave the databas
2d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
2d90: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  n and return [SQ
2da0: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e  LITE_BUSY]..** ^
2db0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  If sqlite3_close
2dc0: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
2dd0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2de0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2df0: 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75  ents.** and/or u
2e00: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
2e10: 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20  3_backups, then 
2e20: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2e30: 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a  nection becomes.
2e40: 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22  ** an unusable "
2e50: 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69  zombie" which wi
2e60: 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
2e70: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
2e80: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74  when the.** last
2e90: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ea0: 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2eb0: 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c   or the last sql
2ec0: 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a  ite3_backup is.*
2ed0: 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65  * finished.  The
2ee0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2ef0: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
2f00: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
2f10: 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c  e with.** host l
2f20: 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72  anguages that ar
2f30: 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63  e garbage collec
2f40: 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74  ted, and where t
2f50: 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63  he order in whic
2f60: 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73  h.** destructors
2f70: 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61   are called is a
2f80: 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  rbitrary..**.** 
2f90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
2fa0: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  uld [sqlite3_fin
2fb0: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2fc0: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20  ] all [prepared 
2fd0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20  statements],.** 
2fe0: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
2ff0: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c  ose | close] all
3000: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
3010: 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
3020: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20  3_backup_finish 
3030: 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73  | finish] all [s
3040: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3050: 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65  bjects associate
3060: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73  d.** with the [s
3070: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
3080: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69  rior to attempti
3090: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
30a0: 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20  object.  ^If.** 
30b0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
30c0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  () is called on 
30d0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
30e0: 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69  ection] that sti
30f0: 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61  ll has.** outsta
3100: 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20  nding [prepared 
3110: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c  statements], [BL
3120: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3130: 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  /or.** [sqlite3_
3140: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3150: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20  then it returns 
3160: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20  [SQLITE_OK] and 
3170: 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e  the deallocation
3180: 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73  .** of resources
3190: 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e 74   is deferred unt
31a0: 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64  il all [prepared
31b0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42   statements], [B
31c0: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a  LOB handles],.**
31d0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61   and [sqlite3_ba
31e0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72  ckup] objects ar
31f0: 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64  e also destroyed
3200: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b  ..**.** ^If an [
3210: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
3220: 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68 69  is destroyed whi
3230: 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  le a transaction
3240: 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65   is open,.** the
3250: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3260: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
3270: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
3280: 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72   The C parameter
3290: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
32a0: 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69  se(C)] and [sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d  te3_close_v2(C)]
32c0: 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
32d0: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
32e0: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
32f0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
3300: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
3310: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
3320: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
3330: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
3340: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
3350: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
3360: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
3370: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
3380: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20  ite3_close() or 
3390: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
33a0: 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  () with a NULL p
33b0: 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65  ointer.** argume
33c0: 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  nt is a harmless
33d0: 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54   no-op..*/.SQLIT
33e0: 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
33f0: 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
3400: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29  _close(sqlite3*)
3410: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
3420: 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3440: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3450: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3460: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
3470: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
3480: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
3490: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
34a0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
34b0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
34c0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
34d0: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
34e0: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
34f0: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
3500: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
3510: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
3520: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
3530: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
3540: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3550: 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
3560: 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
3570: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3580: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
3590: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
35a0: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
35b0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
35c0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
35d0: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
35e0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20  finalize()],.** 
35f0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
3600: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75  pplication to ru
3610: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65  n multiple state
3620: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20  ments of SQL.** 
3630: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
3640: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43  o use a lot of C
3650: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54   code. .**.** ^T
3660: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3670: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73  ) interface runs
3680: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54   zero or more UT
3690: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20  F-8 encoded,.** 
36a0: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
36b0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
36c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74  s passed into it
36d0: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a  s 2nd argument,.
36e0: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ** in the contex
36f0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
3700: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
3710: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20  assed in as its 
3720: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  1st.** argument.
3730: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
3740: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74  ck function of t
3750: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3760: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
3770: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
3780: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76  , then it is inv
3790: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65  oked for each re
37a0: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69  sult row.** comi
37b0: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76  ng out of the ev
37c0: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74  aluated SQL stat
37d0: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74  ements.  ^The 4t
37e0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  h argument to.**
37f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3800: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75  is relayed throu
3810: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72  gh to the 1st ar
3820: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a  gument of each.*
3830: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63  * callback invoc
3840: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20  ation.  ^If the 
3850: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72  callback pointer
3860: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3870: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  ().** is NULL, t
3880: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20  hen no callback 
3890: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20  is ever invoked 
38a0: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20  and result rows 
38b0: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a  are.** ignored..
38c0: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  **.** ^If an err
38d0: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
38e0: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53  evaluating the S
38f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
3900: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  ssed into.** sql
3910: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65  ite3_exec(), the
3920: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  n execution of t
3930: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
3940: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a  ment stops and.*
3950: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61  * subsequent sta
3960: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70  tements are skip
3970: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74  ped.  ^If the 5t
3980: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3990: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
39a0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
39b0: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  n any error mess
39c0: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
39d0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
39e0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
39f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
3a00: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  nd passed back t
3a10: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3a20: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20  arameter..** To 
3a30: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61  avoid memory lea
3a40: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ks, the applicat
3a50: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b  ion should invok
3a60: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
3a70: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d  )].** on error m
3a80: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72  essage strings r
3a90: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
3aa0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3ab0: 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  r of.** of sqlit
3ac0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
3ad0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
3ae0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
3af0: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3b00: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3b10: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3b20: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3b30: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
3b40: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
3b50: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3b60: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
3b70: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
3b80: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
3b90: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
3ba0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
3bb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3bc0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3bd0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
3be0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3bf0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
3c00: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
3c10: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
3c20: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
3c30: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
3c40: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
3c50: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
3c60: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
3c70: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
3c80: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3c90: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
3ca0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
3cb0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
3cc0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
3cd0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
3ce0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3cf0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
3d00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3d10: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3d20: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
3d30: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
3d40: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
3d50: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
3d60: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
3d70: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
3d80: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
3d90: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
3da0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
3db0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
3dc0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
3dd0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3de0: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
3df0: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
3e00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3e20: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3e30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
3e50: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
3e60: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
3e70: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
3e80: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
3e90: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
3ea0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3eb0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
3ec0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
3ed0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3ee0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3ef0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3f00: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
3f10: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
3f20: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
3f30: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
3f40: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
3f50: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
3f60: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
3f70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3f80: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3f90: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
3fa0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
3fb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
3fc0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
3fd0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3fe0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e  lication must in
3ff0: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
4000: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
4010: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
4020: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
4030: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
4040: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
4050: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
4060: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
4070: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74  t close the [dat
4080: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4090: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
40a0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
40b0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
40c0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
40d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
40e0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
40f0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4100: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
4110: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
4120: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
4130: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
4140: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
4150: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
4160: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
4170: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
4180: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
4190: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
41a0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
41b0: 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71  lite3_exec(.  sq
41c0: 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20  lite3*,         
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
41f0: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
4200: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71    const char *sq
4210: 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4230: 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
4240: 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63  ted */.  int (*c
4250: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
4260: 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a  nt,char**,char**
4270: 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  ),  /* Callback 
4280: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
4290: 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20  id *,           
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20           /* 1st 
42c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
42d0: 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a  back */.  char *
42e0: 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20  *errmsg         
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4300: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
4310: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
4320: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
4330: 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64  3REF: Result Cod
4340: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
4350: 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66  {result code def
4360: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4370: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63  Many SQLite func
4380: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20  tions return an 
4390: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63  integer result c
43a0: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74  ode from the set
43b0: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69   shown.** here i
43c0: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63  n order to indic
43d0: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66  ate success or f
43e0: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
43f0: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
4400: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
4410: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
4420: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
4430: 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64  ee also: [extend
4440: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64  ed result code d
4450: 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23  efinitions].*/.#
4460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
4470: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
4480: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
4490: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
44a0: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
44b0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
44c0: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
44d0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
44e0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
44f0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
4500: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
4510: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
4520: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
4530: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
4540: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
4550: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
4560: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
4570: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
4580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
4590: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
45a0: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
45b0: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
45c0: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
45d0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
45e0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
45f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
4600: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
4610: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
4620: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
4630: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
4640: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
4650: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4660: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
4670: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
4680: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
4690: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
46a0: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
46b0: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
46c0: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
46d0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
46e0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
46f0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
4700: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
4710: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
4720: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
4730: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
4740: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
4750: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
4760: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
4770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4780: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
4790: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
47a0: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
47b0: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
47c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
47d0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55  UND    12   /* U
47e0: 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e  nknown opcode in
47f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
4800: 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69  ntrol() */.#defi
4810: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20  ne SQLITE_FULL  
4820: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e        13   /* In
4830: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62  sertion failed b
4840: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20  ecause database 
4850: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69  is full */.#defi
4860: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
4870: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e  EN    14   /* Un
4880: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  able to open the
4890: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
48a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
48b0: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20  _PROTOCOL    15 
48c0: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f    /* Database lo
48d0: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f  ck protocol erro
48e0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
48f0: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20  ITE_EMPTY       
4900: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  16   /* Database
4910: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65   is empty */.#de
4920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45  fine SQLITE_SCHE
4930: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20  MA      17   /* 
4940: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  The database sch
4950: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23  ema changed */.#
4960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f  define SQLITE_TO
4970: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f  OBIG      18   /
4980: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  * String or BLOB
4990: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69   exceeds size li
49a0: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mit */.#define S
49b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
49c0: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20    19   /* Abort 
49d0: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e  due to constrain
49e0: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23  t violation */.#
49f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4a00: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f  SMATCH    20   /
4a10: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d  * Data type mism
4a20: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20  atch */.#define 
4a30: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20  SQLITE_MISUSE   
4a40: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61     21   /* Libra
4a50: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63  ry used incorrec
4a60: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tly */.#define S
4a70: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20  QLITE_NOLFS     
4a80: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f    22   /* Uses O
4a90: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73  S features not s
4aa0: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74  upported on host
4ab0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4ac0: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32  TE_AUTH        2
4ad0: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61  3   /* Authoriza
4ae0: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  tion denied */.#
4af0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f  define SQLITE_FO
4b00: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f  RMAT      24   /
4b10: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61  * Auxiliary data
4b20: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f  base format erro
4b30: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4b40: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20  ITE_RANGE       
4b50: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61  25   /* 2nd para
4b60: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4b70: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e  _bind out of ran
4b80: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge */.#define SQ
4b90: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20  LITE_NOTADB     
4ba0: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70   26   /* File op
4bb0: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74  ened that is not
4bc0: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
4bd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4be0: 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 32  TE_NOTICE      2
4bf0: 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74  7   /* Notificat
4c00: 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 65  ions from sqlite
4c10: 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69  3_log() */.#defi
4c20: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
4c30: 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57 61  G     28   /* Wa
4c40: 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69  rnings from sqli
4c50: 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65  te3_log() */.#de
4c60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
4c70: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
4c80: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4c90: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
4ca0: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
4cb0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
4cc0: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
4cd0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
4ce0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
4cf0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
4d00: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
4d10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
4d20: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
4d30: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4d40: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4d50: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4d60: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  ns}.**.** In its
4d70: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4d80: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4d90: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4da0: 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74  rn one of 30 int
4db0: 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20  eger.** [result 
4dc0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
4dd0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
4de0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
4df0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
4e00: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4e10: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4e20: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4e30: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4e40: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4e50: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4e60: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4e70: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4e80: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4e90: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4ea0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
4eb0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
4ec0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
4ed0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
4ee0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
4ef0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
4f00: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4f10: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4f20: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4f30: 72 73 2e 20 54 68 65 73 65 20 5b 65 78 74 65 6e  rs. These [exten
4f40: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4f50: 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72  ] are enabled or
4f60: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20   disabled.** on 
4f70: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63  a per database c
4f80: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20  onnection basis 
4f90: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
4fa0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
4fb0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41  esult_codes()] A
4fc0: 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 65 78 74  PI.  Or, the ext
4fd0: 65 6e 64 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a  ended code for.*
4fe0: 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  * the most recen
4ff0: 74 20 65 72 72 6f 72 20 63 61 6e 20 62 65 20 6f  t error can be o
5000: 62 74 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  btained using.**
5010: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
5020: 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a  ed_errcode()]..*
5030: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5040: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
5050: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5060: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
5070: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5080: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
5090: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50a0: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
50b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50c0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
50d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50e0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
50f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5100: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
5110: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5120: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
5130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5140: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
5150: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5160: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
5170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5180: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
5190: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51a0: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51c0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51e0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5200: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
5210: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5220: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
5230: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
5240: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
5250: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5260: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
5280: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
5290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52a0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
52b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
52c0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
52d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52e0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
52f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
5300: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
5310: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5320: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
5330: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
5340: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
5350: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5360: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
5370: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
5380: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
5390: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
53a0: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
53b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
53c0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
53d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
53e0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
53f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
5400: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
5410: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5420: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
5430: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
5440: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
5450: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5460: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
5470: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5480: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
5490: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
54a0: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
54b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
54c0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
54d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
54e0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
54f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5500: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
5510: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5520: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
5530: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5540: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5550: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5560: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (21<<8)).#define
5570: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45   SQLITE_IOERR_SE
5580: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EK              
5590: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
55a0: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (22<<8)).#define
55b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
55c0: 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20  LETE_NOENT      
55d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
55e0: 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (23<<8)).#define
55f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d   SQLITE_IOERR_MM
5600: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AP              
5610: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5620: 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (24<<8)).#define
5630: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45   SQLITE_IOERR_GE
5640: 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20  TTEMPPATH       
5650: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5660: 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (25<<8)).#define
5670: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f   SQLITE_IOERR_CO
5680: 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20  NVPATH          
5690: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
56a0: 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (26<<8)).#define
56b0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
56c0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
56d0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
56e0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
56f0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
5700: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
5710: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5720: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5730: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53  ne SQLITE_BUSY_S
5740: 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20  NAPSHOT         
5750: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20    (SQLITE_BUSY  
5760: 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66   |  (2<<8)).#def
5770: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5780: 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20  PEN_NOTEMPDIR   
5790: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
57a0: 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  PEN | (1<<8)).#d
57b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
57c0: 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20  TOPEN_ISDIR     
57d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
57e0: 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a  TOPEN | (2<<8)).
57f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5800: 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48  ANTOPEN_FULLPATH
5810: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5820: 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29  ANTOPEN | (3<<8)
5830: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5840: 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41  _CANTOPEN_CONVPA
5850: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5860: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c  _CANTOPEN | (4<<
5870: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5880: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5890: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
58a0: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
58b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
58c0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
58d0: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
58e0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
58f0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5900: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
5910: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
5920: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5930: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5940: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5950: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
5960: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
5970: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5990: 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20  LY_DBMOVED      
59a0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
59b0: 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  LY | (4<<8)).#de
59c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
59d0: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  T_ROLLBACK      
59e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52      (SQLITE_ABOR
59f0: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5a10: 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20  RAINT_CHECK     
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5a30: 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RAINT | (1<<8)).
5a40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5a50: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54  ONSTRAINT_COMMIT
5a60: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43  HOOK   (SQLITE_C
5a70: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c  ONSTRAINT | (2<<
5a80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a90: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f  TE_CONSTRAINT_FO
5aa0: 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49  REIGNKEY   (SQLI
5ab0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5ac0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5ad0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5ae0: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28  T_FUNCTION     (
5af0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b00: 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  T | (4<<8)).#def
5b10: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5b20: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20  RAINT_NOTNULL   
5b30: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5b40: 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a  RAINT | (5<<8)).
5b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b60: 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52  ONSTRAINT_PRIMAR
5b70: 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  YKEY   (SQLITE_C
5b80: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c  ONSTRAINT | (6<<
5b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5ba0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52  TE_CONSTRAINT_TR
5bb0: 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49  IGGER      (SQLI
5bc0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5bd0: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
5be0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5bf0: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28  T_UNIQUE       (
5c00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c10: 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  T | (8<<8)).#def
5c20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5c30: 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20  RAINT_VTAB      
5c40: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5c50: 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a  RAINT | (9<<8)).
5c60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c70: 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20  ONSTRAINT_ROWID 
5c80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5c90: 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c  ONSTRAINT |(10<<
5ca0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5cb0: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5cc0: 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49  R_WAL      (SQLI
5cd0: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c  TE_NOTICE | (1<<
5ce0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5cf0: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5d00: 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49  R_ROLLBACK (SQLI
5d10: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c  TE_NOTICE | (2<<
5d20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d30: 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49  TE_WARNING_AUTOI
5d40: 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49  NDEX       (SQLI
5d50: 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c  TE_WARNING | (1<
5d60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5d70: 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20 20  ITE_AUTH_USER   
5d80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5d90: 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38  ITE_AUTH | (1<<8
5da0: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
5db0: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
5dc0: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
5dd0: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62  ns.**.** These b
5de0: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  it values are in
5df0: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
5e00: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72  n the.** 3rd par
5e10: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5e20: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5e30: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a  ] interface and.
5e40: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61  ** in the 4th pa
5e50: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
5e60: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
5e70: 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64  n] method..*/.#d
5e80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5e90: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
5ea0: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f     0x00000001  /
5eb0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5ec0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5ee0: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
5ef0: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f     0x00000002  /
5f00: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5f10: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5f20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5f30: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
5f40: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f     0x00000004  /
5f50: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5f60: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5f80: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
5f90: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f     0x00000008  /
5fa0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5fb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5fc0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
5fd0: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f     0x00000010  /
5fe0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6000: 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20  N_AUTOPROXY     
6010: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f     0x00000020  /
6020: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6030: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6040: 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20  N_URI           
6050: 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f     0x00000040  /
6060: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6070: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6090: 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20  N_MEMORY        
60a0: 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f     0x00000080  /
60b0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
60c0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
60d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
60e0: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
60f0: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f     0x00000100  /
6100: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6120: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
6130: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f     0x00000200  /
6140: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6150: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6160: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
6170: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f     0x00000400  /
6180: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
61a0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
61b0: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f     0x00000800  /
61c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
61e0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
61f0: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f     0x00001000  /
6200: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6220: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
6230: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f     0x00002000  /
6240: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6260: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
6270: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f     0x00004000  /
6280: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6290: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
62a0: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20  N_NOMUTEX       
62b0: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f     0x00008000  /
62c0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
62d0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
62e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
62f0: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20  N_FULLMUTEX     
6300: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f     0x00010000  /
6310: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6320: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6340: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  N_SHAREDCACHE   
6350: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f     0x00020000  /
6360: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6370: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6390: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20  N_PRIVATECACHE  
63a0: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f     0x00040000  /
63b0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
63c0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
63d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
63e0: 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  N_WAL           
63f0: 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f     0x00080000  /
6400: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  * VFS only */../
6410: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20  * Reserved:     
6420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6430: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a      0x00F00000 *
6440: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
6450: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63  F: Device Charac
6460: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  teristics.**.** 
6470: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
6480: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
6490: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  d of the [sqlite
64a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
64b0: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20   object returns 
64c0: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
64d0: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20   is a vector of 
64e0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
64f0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
6500: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
6510: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
6520: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
6530: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
6540: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
6550: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6560: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
6570: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
6580: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
6590: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
65a0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
65b0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
65c0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
65d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
65e0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
65f0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
6600: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
6610: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
6620: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
6630: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
6640: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
6650: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
6660: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
6670: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6680: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6690: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
66a0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
66b0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
66c0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
66d0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
66e0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
66f0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
6700: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
6710: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
6720: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
6730: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6740: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
6750: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6760: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
6770: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
6780: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
6790: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
67a0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54   to xWrite().  T
67b0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
67c0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
67d0: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61  ITE property mea
67e0: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72  ns that.** after
67f0: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e   reboot followin
6800: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77  g a crash or pow
6810: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c  er loss, the onl
6820: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20  y bytes in a.** 
6830: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77  file that were w
6840: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70  ritten at the ap
6850: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20  plication level 
6860: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67  might have chang
6870: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61  ed.** and that a
6880: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65  djacent bytes, e
6890: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e  ven bytes within
68a0: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72   the same sector
68b0: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65   are.** guarante
68c0: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67  ed to be unchang
68d0: 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ed.  The SQLITE_
68e0: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
68f0: 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66  E_WHEN_OPEN.** f
6900: 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61  lag indicate tha
6910: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  t a file cannot 
6920: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  be deleted when 
6930: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51  open.  The.** SQ
6940: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6950: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61  ABLE flag indica
6960: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c  tes that the fil
6970: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d  e is on.** read-
6980: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63  only media and c
6990: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
69a0: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73   even by process
69b0: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61  es with.** eleva
69c0: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a  ted privileges..
69d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
69e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6a00: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
6a10: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6a20: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
6a30: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
6a40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a50: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
6a60: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a70: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
6a80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a90: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
6aa0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
6ab0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ac0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
6ad0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6ae0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
6af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6b00: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
6b10: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
6b20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b30: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
6b40: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b50: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
6b60: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6b70: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6b80: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
6b90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6ba0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
6bb0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6bc0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6bd0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6be0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
6bf0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
6c00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6c10: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
6c20: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
6c30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c40: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6c50: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
6c60: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
6c70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6c80: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
6c90: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
6ca0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6cb0: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
6cc0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6cd0: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  2000../*.** CAPI
6ce0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
6cf0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
6d00: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
6d10: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
6d20: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6d30: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6d40: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6d50: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6d60: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6d70: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
6d80: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
6d90: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
6da0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6db0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
6dc0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
6dd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6de0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
6df0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
6e00: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
6e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6e20: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6e30: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6e40: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
6e50: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
6e60: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
6e70: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
6e80: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
6e90: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
6ea0: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
6eb0: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
6ec0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6ed0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
6ee0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
6ef0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6f00: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6f10: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
6f20: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
6f30: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6f40: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
6f50: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
6f60: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
6f70: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
6f80: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
6f90: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
6fa0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
6fb0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
6fc0: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
6fd0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
6fe0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
6ff0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
7000: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
7010: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
7020: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
7030: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
7040: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
7050: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
7060: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
7070: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
7080: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
7090: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
70a0: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
70b0: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
70c0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
70d0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
70e0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
70f0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
7100: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
7110: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
7120: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
7130: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
7140: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
7150: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
7160: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
7170: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
7180: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
7190: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
71a0: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
71b0: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
71c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
71d0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
71e0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
71f0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
7200: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
7210: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
7220: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
7230: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
7240: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
7250: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
7260: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
7270: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
7280: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
7290: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
72a0: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
72b0: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
72c0: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
72d0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
72e0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
72f0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
7300: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
7310: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
7320: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
7330: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
7340: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
7350: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
7360: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
7370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7380: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
7390: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
73a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
73b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
73c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
73d0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
73e0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
73f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7400: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
7410: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
7420: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
7430: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
7440: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
7450: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
7460: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
7470: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
7480: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
7490: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
74a0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
74b0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
74c0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
74d0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
74e0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
74f0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
7500: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
7510: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
7520: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
7530: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7540: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
7550: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
7560: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
7570: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
7580: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
7590: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
75a0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
75b0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
75c0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
75d0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
75e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
75f0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
7600: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
7610: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
7620: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
7630: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7640: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
7650: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
7660: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
7670: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
7680: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7690: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
76a0: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
76b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
76c0: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
76d0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
76e0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
76f0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
7700: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
7710: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
7720: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
7730: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
7740: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
7750: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
7760: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
7770: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
7780: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
7790: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
77a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
77b0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
77c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
77d0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
77e0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
77f0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7800: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
7810: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
7820: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
7830: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
7840: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
7850: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
7860: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
7870: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
7880: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
7890: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
78a0: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
78b0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
78c0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
78d0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
78e0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
78f0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
7900: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
7910: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
7920: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7930: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
7940: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
7950: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
7960: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
7970: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
7980: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
7990: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
79a0: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
79b0: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
79c0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
79d0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
79e0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
79f0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
7a00: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
7a10: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
7a20: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
7a30: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7a40: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
7a50: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
7a60: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
7a70: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
7a80: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
7a90: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
7aa0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
7ab0: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
7ac0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7ad0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7ae0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
7af0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7b00: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7b10: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7b20: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7b30: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7b40: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
7b50: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7b60: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
7b70: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
7b80: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
7b90: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
7ba0: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
7bb0: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
7bc0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
7bd0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
7be0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
7bf0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
7c00: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
7c10: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
7c20: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
7c30: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
7c40: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
7c50: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
7c60: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
7c70: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
7c80: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
7c90: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
7ca0: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
7cb0: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
7cc0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
7cd0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
7ce0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
7cf0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
7d00: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
7d10: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
7d20: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
7d30: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
7d40: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
7d50: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
7d60: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
7d70: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
7d80: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
7d90: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
7da0: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
7db0: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
7dc0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
7dd0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
7de0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
7df0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
7e00: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
7e10: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
7e20: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
7e30: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
7e40: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
7e50: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
7e60: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
7e70: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
7e80: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
7e90: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
7ea0: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
7eb0: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
7ec0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
7ed0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
7ee0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
7ef0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
7f00: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
7f10: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
7f20: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
7f30: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
7f40: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
7f50: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
7f60: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
7f70: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f  odes | list of o
7f80: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
7f90: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
7fa0: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
7fb0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
7fc0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
7fd0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
7fe0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
7ff0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
8000: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
8010: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
8020: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
8030: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
8040: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
8050: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
8060: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
8070: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
8080: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
8090: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
80a0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
80b0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
80c0: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
80d0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
80e0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
80f0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
8100: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
8110: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
8120: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
8130: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
8140: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
8150: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
8160: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8170: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
8180: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
8190: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
81a0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
81b0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
81c0: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
81d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
81e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
81f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8200: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
8210: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8220: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
8230: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8240: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
8250: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8260: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
8270: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8280: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
8290: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
82a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
82b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
82c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
82d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
82e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
82f0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8300: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
8310: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
8320: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8330: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
8340: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
8350: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
8360: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8370: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
8380: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
8390: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
83a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
83b0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
83c0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
83d0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
83e0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
83f0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
8400: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
8410: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
8420: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
8430: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
8440: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8450: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8460: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
8470: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
8480: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8490: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
84a0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
84b0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
84c0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
84d0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
84e0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
84f0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
8500: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8510: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
8520: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8530: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8540: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
8550: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
8560: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
8570: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
8580: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
8590: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
85a0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
85b0: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
85c0: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
85d0: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
85e0: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
85f0: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
8600: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
8610: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8620: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
8630: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
8640: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
8650: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8660: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
8670: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
8680: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
8690: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
86a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
86b0: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
86c0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
86d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
86e0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
86f0: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
8700: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
8710: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8720: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
8730: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
8740: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8750: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8760: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
8770: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
8780: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
8790: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
87a0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
87b0: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
87c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
87d0: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
87e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
87f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8800: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
8810: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
8820: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8830: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
8840: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
8850: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8860: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8870: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
8880: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8890: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
88a0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
88b0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
88c0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
88d0: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
88e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
88f0: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
8900: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
8910: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
8920: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8930: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8940: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
8950: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
8960: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
8970: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8980: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
8990: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
89a0: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
89b0: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
89c0: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
89d0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
89e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
89f0: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
8a00: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
8a10: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
8a20: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
8a30: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
8a40: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
8a50: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
8a60: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
8a70: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8a80: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8a90: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
8aa0: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
8ab0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8ac0: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
8ad0: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
8ae0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
8af0: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8b00: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8b10: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
8b20: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8b30: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8b40: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
8b50: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
8b60: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
8b70: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
8b80: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
8b90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
8ba0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
8bb0: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b  rol Opcodes.** K
8bc0: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63  EYWORDS: {file c
8bd0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20  ontrol opcodes} 
8be0: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
8bf0: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  code}.**.** Thes
8c00: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
8c10: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
8c20: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
8c30: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
8c40: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
8c50: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
8c60: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
8c70: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8c80: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
8c90: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ace..**.** <ul>.
8ca0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8cb0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
8cc0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8cd0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8ce0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8cf0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
8d00: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
8d10: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
8d20: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
8d30: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
8d40: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
8d50: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
8d60: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
8d70: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
8d80: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
8d90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8da0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
8db0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
8dc0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8dd0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
8de0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
8df0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
8e00: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
8e10: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
8e20: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
8e30: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f  testing and is o
8e40: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68  nly available wh
8e50: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  en the SQLITE_TE
8e60: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  ST.** compile-ti
8e70: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  me option is use
8e80: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
8e90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
8ea0: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
8eb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
8ec0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
8ed0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
8ee0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
8ef0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
8f00: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
8f10: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
8f20: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
8f30: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
8f40: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
8f50: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
8f60: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
8f70: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
8f80: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
8f90: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
8fa0: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
8fb0: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
8fc0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
8fd0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
8fe0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
8ff0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
9000: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
9010: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
9020: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
9030: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9040: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9050: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
9060: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9070: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
9080: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
9090: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
90a0: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
90b0: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
90c0: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
90d0: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
90e0: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
90f0: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
9100: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
9110: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9120: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
9130: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
9140: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
9150: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
9160: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
9170: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
9180: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
9190: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
91a0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
91b0: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
91c0: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
91d0: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
91e0: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
91f0: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
9200: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
9210: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
9220: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
9230: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9240: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9250: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
9260: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9270: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
9280: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
9290: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
92a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
92b0: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
92c0: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74  ated with a part
92d0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
92e0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
92f0: 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  See the [sqlite3
9300: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9310: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
9320: 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
9330: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
9340: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9350: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
9360: 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67  TED]].** No long
9370: 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a  er in use..**.**
9380: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9390: 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68  NTL_SYNC]].** Th
93a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
93b0: 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20  SYNC] opcode is 
93c0: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
93d0: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61  ally by SQLite a
93e0: 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68  nd.** sent to th
93f0: 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c  e VFS immediatel
9400: 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79  y before the xSy
9410: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  nc method is inv
9420: 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74  oked on a.** dat
9430: 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72  abase file descr
9440: 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68  iptor. Or, if th
9450: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
9460: 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a  s not invoked .*
9470: 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73  * because the us
9480: 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65  er has configure
9490: 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a  d SQLite with .*
94a0: 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  * [PRAGMA synchr
94b0: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73  onous | PRAGMA s
94c0: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20  ynchronous=OFF] 
94d0: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e  it is invoked in
94e0: 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68   place .** of th
94f0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20  e xSync method. 
9500: 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74  In most cases, t
9510: 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
9520: 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a  ent passed with.
9530: 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  ** this file-con
9540: 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f  trol is NULL. Ho
9550: 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61  wever, if the da
9560: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62  tabase file is b
9570: 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61  eing synced.** a
9580: 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74  s part of a mult
9590: 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69  i-database commi
95a0: 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  t, the argument 
95b0: 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d  points to a nul-
95c0: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
95d0: 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
95e0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  the transactions
95f0: 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20   master-journal 
9600: 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73  file name. VFSes
9610: 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74   that .** do not
9620: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9630: 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  l should silentl
9640: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
9650: 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f  code. Applicatio
9660: 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f  ns .** should no
9670: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
9680: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9690: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65  with this opcode
96a0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
96b0: 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65   .** disrupt the
96c0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
96d0: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
96e0: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75  Ses that do requ
96f0: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20  ire it.  .**.** 
9700: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9710: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
9720: 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  WO]].** The [SQL
9730: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
9740: 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64  _PHASETWO] opcod
9750: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
9760: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
9770: 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20  ite.** and sent 
9780: 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72  to the VFS after
9790: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68   a transaction h
97a0: 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65  as been committe
97b0: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a  d immediately.**
97c0: 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20   but before the 
97d0: 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f  database is unlo
97e0: 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74  cked. VFSes that
97f0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
9800: 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75  s signal.** shou
9810: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9820: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
9830: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
9840: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20  uld not call.** 
9850: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9860: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9870: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9880: 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70  ng so may disrup
9890: 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74  t the .** operat
98a0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
98b0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
98c0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
98d0: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
98e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
98f0: 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20  2_AV_RETRY]].** 
9900: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9910: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
9920: 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  Y] opcode is use
9930: 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61  d to configure a
9940: 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72  utomatic.** retr
9950: 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74  y counts and int
9960: 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61  ervals for certa
9970: 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72  in disk I/O oper
9980: 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a  ations for the.*
9990: 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20  * windows [VFS] 
99a0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76  in order to prov
99b0: 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69  ide robustness i
99c0: 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  n the presence o
99d0: 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20  f.** anti-virus 
99e0: 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65  programs.  By de
99f0: 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f  fault, the windo
9a00: 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72  ws VFS will retr
9a10: 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20  y file read,.** 
9a20: 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20  file write, and 
9a30: 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72  file delete oper
9a40: 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20  ations up to 10 
9a50: 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65  times, with a de
9a60: 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c  lay.** of 25 mil
9a70: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65  liseconds before
9a80: 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79   the first retry
9a90: 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65   and with the de
9aa0: 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a  lay increasing.*
9ab0: 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e  * by an addition
9ac0: 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  al 25 millisecon
9ad0: 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62  ds with each sub
9ae0: 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20  sequent retry.  
9af0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  This.** opcode a
9b00: 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20  llows these two 
9b10: 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69  values (10 retri
9b20: 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73  es and 25 millis
9b30: 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29  econds of delay)
9b40: 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74  .** to be adjust
9b50: 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20  ed.  The values 
9b60: 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20  are changed for 
9b70: 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e  all database con
9b80: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  nections.** with
9b90: 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63  in the same proc
9ba0: 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ess.  The argume
9bb0: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
9bc0: 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74  to an array of t
9bd0: 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77  wo.** integers w
9be0: 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69  here the first i
9bf0: 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77  nteger i the new
9c00: 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64   retry count and
9c10: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69   the second.** i
9c20: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65  nteger is the de
9c30: 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20  lay.  If either 
9c40: 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74  integer is negat
9c50: 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65  ive, then the se
9c60: 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20  tting.** is not 
9c70: 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74  changed but inst
9c80: 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61  ead the prior va
9c90: 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74  lue of that sett
9ca0: 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  ing is written.*
9cb0: 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79  * into the array
9cc0: 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67   entry, allowing
9cd0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74   the current ret
9ce0: 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62  ry settings to b
9cf0: 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65  e.** interrogate
9d00: 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20  d.  The zDbName 
9d10: 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e  parameter is ign
9d20: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ored..**.** <li>
9d30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
9d40: 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20  ERSIST_WAL]].** 
9d50: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9d60: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20  TL_PERSIST_WAL] 
9d70: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9d80: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
9d90: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
9da0: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68   [WAL | Write Ah
9db0: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67  ead Log] setting
9dc0: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
9dd0: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20  he auxiliary.** 
9de0: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20  write ahead log 
9df0: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
9e00: 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72  y files used for
9e10: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
9e20: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f  trol.** are auto
9e30: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
9e40: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73  d when the lates
9e50: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  t connection to 
9e60: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
9e70: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67  closes.  Setting
9e80: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
9e90: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73  mode causes thos
9ea0: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69  e files to persi
9eb0: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73  st after.** clos
9ec0: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74  e.  Persisting t
9ed0: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66  he files is usef
9ee0: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72  ul when other pr
9ef0: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20  ocesses that do 
9f00: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74  not.** have writ
9f10: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20  e permission on 
9f20: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f  the directory co
9f30: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74  ntaining the dat
9f40: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a  abase file want.
9f50: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64  ** to read the d
9f60: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73  atabase file, as
9f70: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61   the WAL and sha
9f80: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9f90: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69   must exist.** i
9fa0: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20  n order for the 
9fb0: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  database to be r
9fc0: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f  eadable.  The fo
9fd0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
9fe0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
9ff0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a000: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a010: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a020: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a030: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a040: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a050: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
a060: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
a070: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  ble persistent.*
a080: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20  * WAL mode.  If 
a090: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
a0a0: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
a0b0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
a0c0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41  he current.** WA
a0d0: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65  L persistence se
a0e0: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
a0f0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a100: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a110: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a120: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
a130: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a140: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
a150: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
a160: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
a170: 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65  t "powersafe-ove
a180: 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57  rwrite" or "PSOW
a190: 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20  " setting.  The 
a1a0: 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20  PSOW setting.** 
a1b0: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b  determines the [
a1c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
a1d0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a1e0: 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20  ] bit of the.** 
a1f0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
a200: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20  istics methods. 
a210: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
a220: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
a230: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a240: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
a250: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
a260: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
a270: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
a280: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
a290: 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  isable zero-dama
a2a0: 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  ge mode or 1 to 
a2b0: 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  enable zero-dama
a2c0: 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20  ge.** mode.  If 
a2d0: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
a2e0: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
a2f0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
a300: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65  he current.** ze
a310: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73  ro-damage mode s
a320: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
a330: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a340: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
a350: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a360: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  TL_OVERWRITE] op
a370: 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  code is invoked 
a380: 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20  by SQLite after 
a390: 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69  opening.** a wri
a3a0: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  te transaction t
a3b0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c  o indicate that,
a3c0: 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f   unless it is ro
a3d0: 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f  lled back for so
a3e0: 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68  me.** reason, th
a3f0: 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73  e entire databas
a400: 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f  e file will be o
a410: 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68  verwritten by th
a420: 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72  e current .** tr
a430: 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20  ansaction. This 
a440: 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55  is used by VACUU
a450: 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  M operations..**
a460: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a470: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d  _FCNTL_VFSNAME]]
a480: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a490: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20  _FCNTL_VFSNAME] 
a4a0: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
a4b0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
a4c0: 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c   names of.** all
a4d0: 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20   [VFSes] in the 
a4e0: 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20  VFS stack.  The 
a4f0: 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c  names are of all
a500: 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74   VFS shims and t
a510: 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74  he.** final bott
a520: 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65  om-level VFS are
a530: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
a540: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
a550: 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
a560: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68  malloc()] and th
a570: 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72  e result is stor
a580: 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20  ed in the char* 
a590: 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74  variable.** that
a5a0: 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
a5b0: 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65  meter of [sqlite
a5c0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a5d0: 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20  ] points to..** 
a5e0: 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65  The caller is re
a5f0: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72  sponsible for fr
a600: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79  eeing the memory
a610: 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20   when done.  As 
a620: 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65  with.** all file
a630: 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73  -control actions
a640: 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75  , there is no gu
a650: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69  arantee that thi
a660: 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a  s will actually.
a670: 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20  ** do anything. 
a680: 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20   Callers should 
a690: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63  initialize the c
a6a0: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f  har* variable to
a6b0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
a6c0: 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20  er in case this 
a6d0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
a6e0: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e  not implemented.
a6f0: 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74    This file-cont
a700: 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64  rol.** is intend
a710: 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69  ed for diagnosti
a720: 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  c use only..**.*
a730: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a740: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
a750: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
a760: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
a770: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
a780: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a790: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
a7a0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
a7b0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
a7c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
a7d0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
a7e0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
a7f0: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
a800: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
a810: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
a820: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
a830: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a840: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a850: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
a860: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
a870: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
a880: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
a890: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
a8a0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
a8b0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
a8c0: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
a8d0: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
a8e0: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
a8f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
a900: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
a910: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
a920: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
a930: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
a940: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a950: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
a960: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
a970: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
a980: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
a990: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
a9a0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
a9b0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
a9c0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
a9d0: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
a9e0: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
a9f0: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
aa00: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
aa10: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
aa20: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
aa30: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
aa40: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
aa50: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
aa60: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
aa70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
aa80: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
aa90: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
aaa0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
aab0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
aac0: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
aad0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
aae0: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
aaf0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
ab00: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
ab10: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
ab20: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
ab30: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
ab40: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
ab50: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
ab60: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
ab70: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
ab80: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c  atement if resul
ab90: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c  t string is NULL
aba0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e  , or that return
abb0: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
abc0: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  he result string
abd0: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   if the string i
abe0: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e  s non-NULL..** ^
abf0: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
ac00: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ac10: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
ac20: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
ac30: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
ac40: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
ac50: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
ac60: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
ac70: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
ac80: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
ac90: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
aca0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
acb0: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
acc0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
acd0: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
ace0: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
acf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ad00: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
ad10: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
ad20: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
ad30: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
ad40: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
ad50: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
ad60: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
ad70: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
ad80: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
ad90: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ada0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
adb0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
adc0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
add0: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
ade0: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
adf0: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
ae00: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
ae10: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
ae20: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
ae30: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
ae40: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
ae50: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
ae60: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
ae70: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
ae80: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
ae90: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
aea0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
aeb0: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
aec0: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
aed0: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
aee0: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
aef0: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
af00: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
af10: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
af20: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
af30: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
af40: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
af50: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
af60: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
af70: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
af80: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
af90: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
afa0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
afb0: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
afc0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
afd0: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
afe0: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
aff0: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
b000: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
b010: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
b020: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
b030: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
b040: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
b050: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b060: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
b070: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
b080: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
b090: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b0a0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
b0b0: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
b0c0: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
b0d0: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
b0e0: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
b0f0: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
b100: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
b110: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
b120: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b130: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
b140: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
b150: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
b160: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
b170: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
b180: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
b190: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b1a0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
b1b0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
b1c0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
b1d0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
b1e0: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
b1f0: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
b200: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
b210: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
b220: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
b230: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
b240: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b250: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
b260: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b270: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
b280: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b290: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
b2a0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
b2b0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
b2c0: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
b2d0: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
b2e0: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
b2f0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
b300: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
b310: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
b320: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
b330: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
b340: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b350: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
b360: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
b370: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
b380: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
b390: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
b3a0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
b3b0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
b3c0: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
b3d0: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
b3e0: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
b3f0: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
b400: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
b410: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
b420: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
b430: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
b440: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
b450: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
b460: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
b470: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
b480: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
b490: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
b4a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
b4b0: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
b4c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b4d0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
b4e0: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
b4f0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
b500: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
b510: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
b520: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
b530: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
b540: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
b550: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
b560: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
b570: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
b580: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
b590: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
b5a0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
b5b0: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
b5c0: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
b5d0: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
b5e0: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
b5f0: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
b600: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
b610: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
b620: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
b630: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
b640: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
b650: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b660: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
b670: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b680: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
b690: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
b6a0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
b6b0: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
b6c0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
b6d0: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
b6e0: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
b6f0: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
b700: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
b710: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
b720: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
b730: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
b740: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
b750: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
b760: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
b770: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b780: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
b790: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
b7a0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
b7b0: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
b7c0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
b7d0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
b7e0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
b7f0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
b800: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
b810: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
b820: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
b830: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
b840: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
b850: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
b860: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
b870: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
b880: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
b890: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
b8a0: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
b8b0: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  efined..**.** <l
b8c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b8d0: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20  _WAL_BLOCK]].** 
b8e0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b8f0: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20  L_WAL_BLOCK] is 
b900: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
b910: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69  VFS layer that i
b920: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64  t might.** be ad
b930: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c  vantageous to bl
b940: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  ock on the next 
b950: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20  WAL lock if the 
b960: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65  lock is not imme
b970: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c  diately.** avail
b980: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73  able.  The WAL s
b990: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20  ubsystem issues 
b9a0: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69  this signal duri
b9b0: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75  ng rare.** circu
b9c0: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65  mstances in orde
b9d0: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c  r to fix a probl
b9e0: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79  em with priority
b9f0: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41   inversion..** A
ba00: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
ba10: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  ld <em>not</em> 
ba20: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  use this file-co
ba30: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ntrol..**.** <li
ba40: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
ba50: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20  ZIPVFS]].** The 
ba60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
ba70: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20  PVFS] opcode is 
ba80: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a  implemented by z
ba90: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20  ipvfs only. All 
baa0: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f  other.** VFS sho
bab0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
bac0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74  E_NOTFOUND for t
bad0: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a  his opcode..**.*
bae0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
baf0: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68  CNTL_RBU]].** Th
bb00: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bb10: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  RBU] opcode is i
bb20: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
bb30: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73  e special VFS us
bb40: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55  ed by.** the RBU
bb50: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e   extension only.
bb60: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20    All other VFS 
bb70: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
bb80: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
bb90: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65  r.** this opcode
bba0: 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .  .** </ul>.*/.
bbb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bbc0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
bbd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
bbe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bbf0: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
bc00: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
bc10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bc20: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
bc30: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
bc40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bc50: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
bc60: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
bc70: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bc80: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
bc90: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
bca0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bcb0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
bcc0: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
bcd0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
bce0: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
bcf0: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
bd00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
bd10: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
bd20: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
bd30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bd40: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
bd50: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
bd60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
bd70: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
bd80: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
bd90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
bda0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
bdb0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
bdc0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
bdd0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
bde0: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
bdf0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
be00: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
be10: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
be20: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
be30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
be40: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
be50: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
be60: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
be70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
be80: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
be90: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
bea0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
beb0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
bec0: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
bed0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bee0: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
bef0: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
bf00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bf10: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
bf20: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
bf30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bf40: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
bf50: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
bf60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bf70: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
bf80: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69          22.#defi
bf90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bfa0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
bfb0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e         23.#defin
bfc0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
bfd0: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20  AL_BLOCK        
bfe0: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65        24.#define
bff0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49   SQLITE_FCNTL_ZI
c000: 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20  PVFS            
c010: 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20       25.#define 
c020: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
c030: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c040: 20 20 20 20 32 36 0a 0a 2f 2a 20 64 65 70 72 65      26../* depre
c050: 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23  cated names */.#
c060: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45  define SQLITE_GE
c070: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
c080: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
c090: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_GET_LOCKPROXYF
c0a0: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
c0b0: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
c0c0: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
c0d0: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
c0e0: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
c0f0: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
c100: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53  NO             S
c110: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
c120: 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  _ERRNO.../*.** C
c130: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
c140: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  andle.**.** The 
c150: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
c160: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
c170: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
c180: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
c190: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
c1a0: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
c1b0: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
c1c0: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
c1d0: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
c1e0: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
c1f0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
c200: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
c210: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
c220: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
c230: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
c240: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
c250: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
c260: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
c270: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
c280: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
c290: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
c2a0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
c2b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
c2c0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
c2d0: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
c2e0: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
c2f0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
c300: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
c310: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
c320: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
c330: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
c340: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
c350: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
c360: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
c370: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
c380: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
c390: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20   file system".  
c3a0: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20  See.** the [VFS 
c3b0: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74  | VFS documentat
c3c0: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72  ion] for further
c3d0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
c3e0: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
c3f0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
c400: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
c410: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
c420: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
c430: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
c440: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
c450: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
c460: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
c470: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
c480: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
c490: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
c4a0: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
c4b0: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
c4c0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
c4d0: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
c4e0: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
c4f0: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
c500: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
c510: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
c520: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
c530: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
c540: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
c550: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
c560: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
c570: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
c580: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
c590: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
c5a0: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
c5b0: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
c5c0: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
c5d0: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
c5e0: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
c5f0: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
c600: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
c610: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
c620: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
c630: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
c640: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
c650: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
c660: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
c670: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
c680: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
c690: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
c6a0: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
c6b0: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
c6c0: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
c6d0: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
c6e0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
c6f0: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
c700: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
c710: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
c720: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
c730: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
c740: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
c750: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
c760: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
c770: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
c780: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
c790: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
c7a0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
c7b0: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
c7c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
c7d0: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
c7e0: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
c7f0: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
c800: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
c810: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
c820: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
c830: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
c840: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
c850: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
c860: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
c870: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
c880: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
c890: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
c8a0: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
c8b0: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
c8c0: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
c8d0: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
c8e0: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
c8f0: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
c900: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
c910: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
c920: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
c930: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
c940: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
c950: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
c960: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
c970: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
c980: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
c990: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
c9a0: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
c9b0: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
c9c0: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
c9d0: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
c9e0: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
c9f0: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
ca00: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
ca10: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
ca20: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
ca30: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
ca40: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
ca50: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
ca60: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
ca70: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
ca80: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
ca90: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
caa0: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
cab0: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
cac0: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
cad0: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
cae0: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
caf0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
cb00: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
cb10: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
cb20: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
cb30: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
cb40: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
cb50: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
cb60: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
cb70: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
cb80: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
cb90: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
cba0: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
cbb0: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
cbc0: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
cbd0: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
cbe0: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
cbf0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
cc00: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
cc10: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
cc20: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
cc30: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
cc40: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
cc50: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
cc60: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
cc70: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
cc80: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
cc90: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
cca0: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
ccb0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
ccc0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
ccd0: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
cce0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
ccf0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
cd00: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
cd10: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
cd20: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
cd30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
cd40: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
cd50: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
cd60: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
cd70: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
cd80: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
cd90: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
cda0: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
cdb0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
cdc0: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
cdd0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
cde0: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
cdf0: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
ce00: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
ce10: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
ce20: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
ce30: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
ce40: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
ce50: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
ce60: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
ce70: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
ce80: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
ce90: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
cea0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
ceb0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
cec0: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
ced0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cee0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
cef0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
cf00: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
cf10: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
cf20: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
cf30: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
cf40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
cf50: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
cf60: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cf70: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
cf80: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
cf90: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
cfa0: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
cfb0: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
cfc0: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
cfd0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
cfe0: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
cff0: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
d000: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
d010: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
d020: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
d030: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
d040: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
d050: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
d060: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
d070: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
d080: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
d090: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
d0a0: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
d0b0: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
d0c0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
d0d0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
d0e0: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
d0f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
d100: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
d110: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
d120: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
d130: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
d140: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
d150: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
d160: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
d170: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
d180: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
d190: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
d1a0: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
d1b0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
d1c0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
d1d0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
d1e0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
d1f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
d200: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d210: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
d220: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
d230: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
d240: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
d250: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
d260: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
d270: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
d280: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
d290: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
d2a0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
d2b0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
d2c0: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
d2d0: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
d2e0: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
d2f0: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
d300: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
d310: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
d320: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
d330: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
d340: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
d350: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
d360: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
d370: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
d380: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
d390: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
d3a0: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
d3b0: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
d3c0: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
d3d0: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
d3e0: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
d3f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
d400: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
d410: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
d420: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
d430: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
d440: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
d450: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
d460: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
d470: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
d480: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
d490: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
d4a0: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
d4b0: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
d4c0: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
d4d0: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
d4e0: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
d4f0: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
d500: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
d510: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
d520: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
d530: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
d540: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
d550: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
d560: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
d570: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
d580: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
d590: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
d5a0: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
d5b0: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
d5c0: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
d5d0: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
d5e0: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
d5f0: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
d600: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
d610: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
d620: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
d630: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
d640: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
d650: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
d660: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
d670: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
d680: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
d690: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
d6a0: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
d6b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
d6c0: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
d6d0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
d6e0: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
d6f0: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
d700: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
d710: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
d720: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
d730: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
d740: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
d750: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
d760: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
d770: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
d780: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
d790: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
d7a0: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
d7b0: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
d7c0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
d7d0: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
d7e0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
d7f0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
d800: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
d810: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
d820: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
d830: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
d840: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
d850: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
d860: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
d870: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
d880: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
d890: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
d8a0: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
d8b0: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
d8c0: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
d8d0: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
d8e0: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
d8f0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
d900: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
d910: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
d920: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
d930: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
d940: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
d950: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
d960: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
d970: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
d980: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
d990: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
d9a0: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
d9b0: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
d9c0: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
d9d0: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
d9e0: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
d9f0: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
da00: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
da10: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
da20: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
da30: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
da40: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
da50: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
da60: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
da70: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
da80: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
da90: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
daa0: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
dab0: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
dac0: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
dad0: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
dae0: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
daf0: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
db00: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
db10: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
db20: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
db30: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
db40: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
db50: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
db60: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
db70: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
db80: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
db90: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
dba0: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
dbb0: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
dbc0: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
dbd0: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
dbe0: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
dbf0: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
dc00: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
dc10: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
dc20: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
dc30: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
dc40: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
dc50: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
dc60: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
dc70: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
dc80: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
dc90: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
dca0: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
dcb0: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
dcc0: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
dcd0: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
dce0: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
dcf0: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
dd00: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
dd10: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
dd20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
dd30: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
dd40: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
dd50: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
dd60: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
dd70: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
dd80: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
dd90: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
dda0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
ddb0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
ddc0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
ddd0: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
dde0: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
ddf0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
de00: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
de10: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
de20: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
de30: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
de40: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
de50: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
de60: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
de70: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
de80: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
de90: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
dea0: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
deb0: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
dec0: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
ded0: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
dee0: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
def0: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
df00: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
df10: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
df20: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
df30: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
df40: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
df50: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
df60: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
df70: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
df80: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
df90: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
dfa0: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
dfb0: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
dfc0: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
dfd0: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
dfe0: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
dff0: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
e000: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
e010: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
e020: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
e030: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
e040: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
e050: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
e060: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
e070: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
e080: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
e090: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
e0a0: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
e0b0: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
e0c0: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
e0d0: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
e0e0: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
e0f0: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
e100: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
e110: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
e120: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
e130: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
e140: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
e150: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
e160: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
e170: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
e180: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
e190: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
e1a0: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
e1b0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
e1c0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
e1d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
e1e0: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
e1f0: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
e200: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
e210: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
e220: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
e230: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
e240: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
e250: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
e260: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
e270: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
e280: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
e290: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
e2a0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
e2b0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
e2c0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
e2d0: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
e2e0: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
e2f0: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
e300: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
e310: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
e320: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
e330: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
e340: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
e350: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e360: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
e370: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
e380: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
e390: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
e3a0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
e3b0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
e3c0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e3d0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
e3e0: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
e3f0: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
e400: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e410: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
e420: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
e430: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
e440: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
e450: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e460: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
e470: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
e480: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
e490: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
e4a0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e4b0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
e4c0: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
e4d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e4e0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
e4f0: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
e500: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
e510: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
e520: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
e530: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
e540: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
e550: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e560: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
e570: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
e580: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
e590: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
e5a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
e5b0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
e5c0: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
e5d0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
e5e0: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
e5f0: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
e600: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
e610: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
e620: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
e630: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
e640: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e650: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
e660: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
e670: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
e680: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
e690: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
e6a0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
e6b0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
e6c0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
e6d0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
e6e0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
e6f0: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
e700: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e710: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e720: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
e730: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
e740: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
e750: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
e760: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
e770: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
e780: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
e790: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
e7a0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e7b0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
e7c0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
e7d0: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
e7e0: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
e7f0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e800: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e810: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
e820: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
e830: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
e840: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e850: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
e860: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
e870: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
e880: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
e890: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
e8a0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
e8b0: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
e8c0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
e8d0: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
e8e0: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
e8f0: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
e900: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
e910: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
e920: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
e930: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
e940: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
e950: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
e960: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
e970: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
e980: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
e990: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
e9a0: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
e9b0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
e9c0: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
e9d0: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
e9e0: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
e9f0: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
ea00: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ea10: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
ea20: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
ea30: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
ea40: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ea50: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
ea60: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
ea70: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
ea80: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
ea90: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
eaa0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
eab0: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
eac0: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
ead0: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
eae0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
eaf0: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
eb00: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
eb10: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
eb20: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
eb30: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
eb40: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
eb50: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
eb60: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
eb70: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
eb80: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
eb90: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
eba0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
ebb0: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
ebc0: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
ebd0: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
ebe0: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
ebf0: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
ec00: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
ec10: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
ec20: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
ec30: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
ec40: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
ec50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
ec60: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
ec70: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
ec80: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
ec90: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
eca0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
ecb0: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
ecc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
ecd0: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
ece0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ecf0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
ed00: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
ed10: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
ed20: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
ed30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
ed40: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
ed50: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
ed60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ed70: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
ed80: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
ed90: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
eda0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
edb0: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
edc0: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
edd0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
ede0: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
edf0: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
ee00: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
ee10: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
ee20: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
ee30: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
ee40: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
ee50: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
ee60: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
ee70: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
ee80: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
ee90: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
eea0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
eeb0: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
eec0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
eed0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
eee0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
eef0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
ef00: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
ef10: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
ef20: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
ef30: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
ef40: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
ef50: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
ef60: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
ef70: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
ef80: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
ef90: 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
efa0: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
efb0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
efc0: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
efd0: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
efe0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
eff0: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
f000: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
f010: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
f020: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
f030: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
f040: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
f050: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
f060: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
f070: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
f080: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
f090: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
f0a0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
f0b0: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
f0c0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
f0d0: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
f0e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
f0f0: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
f100: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
f110: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
f120: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
f130: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
f140: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
f150: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
f160: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
f170: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
f180: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
f190: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
f1a0: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
f1b0: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
f1c0: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
f1d0: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
f1e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f1f0: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
f200: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
f210: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
f220: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
f230: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
f240: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f250: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
f260: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
f270: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
f280: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
f290: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
f2a0: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
f2b0: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
f2c0: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
f2d0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
f2e0: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
f2f0: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
f300: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
f310: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
f320: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
f330: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
f340: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
f350: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
f360: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
f370: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
f380: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
f390: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
f3a0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
f3b0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
f3c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f3d0: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
f3e0: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
f3f0: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
f400: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
f410: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
f420: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
f430: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
f440: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
f450: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
f460: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
f470: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f480: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
f490: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
f4a0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f4b0: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
f4c0: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
f4d0: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
f4e0: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
f4f0: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
f500: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
f510: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
f520: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
f530: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
f540: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f550: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
f560: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
f570: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
f580: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
f590: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
f5a0: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
f5b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
f5c0: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
f5d0: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
f5e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f5f0: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
f600: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
f610: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
f620: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
f630: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
f640: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
f650: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
f660: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f670: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
f680: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
f690: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f6a0: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
f6b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f6c0: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
f6d0: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
f6e0: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
f6f0: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
f700: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
f710: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
f720: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
f730: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
f740: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
f750: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
f760: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
f770: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
f780: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
f790: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
f7a0: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
f7b0: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
f7c0: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
f7d0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
f7e0: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
f7f0: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
f800: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
f810: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
f820: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f830: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f840: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
f850: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
f860: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
f870: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
f880: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f890: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
f8a0: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
f8b0: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
f8c0: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
f8d0: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
f8e0: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
f8f0: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
f900: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
f910: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
f920: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
f930: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
f940: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f950: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
f960: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
f970: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
f980: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
f990: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
f9a0: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
f9b0: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
f9c0: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
f9d0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f9e0: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
f9f0: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
fa00: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
fa10: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
fa20: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
fa30: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
fa40: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
fa50: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
fa60: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
fa70: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
fa80: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
fa90: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
faa0: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
fab0: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
fac0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
fad0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
fae0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
faf0: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
fb00: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
fb10: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
fb20: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
fb30: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
fb40: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
fb50: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
fb60: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
fb70: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
fb80: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
fb90: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
fba0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
fbb0: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
fbc0: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
fbd0: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
fbe0: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
fbf0: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
fc00: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fc10: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
fc20: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
fc30: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
fc40: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
fc50: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
fc60: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
fc70: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
fc80: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
fc90: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
fca0: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
fcb0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
fcc0: 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
fcd0: 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
fce0: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
fcf0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
fd00: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
fd10: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
fd20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
fd30: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
fd40: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
fd50: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
fd60: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
fd70: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
fd80: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
fd90: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
fda0: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
fdb0: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
fdc0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
fdd0: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
fde0: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
fdf0: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
fe00: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
fe10: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
fe20: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
fe30: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
fe40: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
fe50: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
fe60: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
fe70: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
fe80: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
fe90: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
fea0: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
feb0: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
fec0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
fed0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
fee0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
fef0: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
ff00: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
ff10: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
ff20: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
ff30: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
ff40: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
ff50: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
ff60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ff70: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
ff80: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
ff90: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
ffa0: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
ffb0: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
ffc0: 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
ffd0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ffe0: 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
fff0: 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
10000 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
10010 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
10020 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
10030 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
10040 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
10050 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
10060 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
10070 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
10080 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
10090 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
100a0 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
100b0 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
100c0 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
100d0 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
100e0 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
100f0 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
10100 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
10110 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
10120 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
10130 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
10140 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
10150 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
10160 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
10170 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
10180 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
10190 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
101a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
101b0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
101c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
101d0 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
101e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
101f0 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
10200 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
10210 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
10220 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54  ailure..*/.SQLIT
10230 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
10240 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
10250 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
10260 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
10270 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
10280 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10290 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  n(void);.SQLITE_
102a0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
102b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f  TDCALL sqlite3_o
102c0 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51  s_init(void);.SQ
102d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
102e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
102f0 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
10300 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10310 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
10320 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
10330 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
10340 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
10350 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
10360 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
10370 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
10380 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
10390 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
103a0 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
103b0 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
103c0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
103d0 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
103e0 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
103f0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
10400 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
10410 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
10420 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
10430 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
10440 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
10450 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
10460 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
10470 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
10480 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
10490 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
104a0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
104b0 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
104c0 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
104d0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
104e0 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
104f0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10500 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
10510 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
10520 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
10530 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
10540 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
10550 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
10560 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
10570 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
10580 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
10590 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
105a0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
105b0 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
105c0 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
105d0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
105e0 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
105f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10600 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
10610 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10620 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
10630 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
10640 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
10650 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
10660 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
10670 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
10680 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
10690 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
106a0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
106b0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
106c0 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
106d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
106e0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
106f0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
10700 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
10710 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10720 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
10730 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
10740 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
10750 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
10760 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
10770 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
10780 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
10790 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
107a0 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
107b0 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
107c0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
107d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
107e0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
107f0 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
10800 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
10810 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
10820 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
10830 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
10840 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
10850 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
10860 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
10870 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
10880 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
10890 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
108a0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
108b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
108c0 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c  int SQLITE_CDECL
108d0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
108e0 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
108f0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
10900 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
10910 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
10920 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
10930 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10940 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
10950 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
10960 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
10970 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
10980 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
10990 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
109a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
109b0 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
109c0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
109d0 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
109e0 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
109f0 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
10a00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10a10 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
10a20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10a30 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
10a40 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
10a50 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
10a60 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
10a70 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
10a80 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
10a90 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
10aa0 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
10ab0 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
10ac0 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
10ad0 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
10ae0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10af0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
10b00 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
10b10 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
10b20 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
10b30 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
10b40 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
10b50 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
10b60 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
10b70 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
10b80 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
10b90 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
10ba0 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
10bb0 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ssful..*/.SQLITE
10bc0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
10bd0 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 64 62  CDECL sqlite3_db
10be0 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
10bf0 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
10c00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10c10 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
10c20 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
10c30 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
10c40 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
10c50 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
10c60 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
10c70 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
10c80 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
10c90 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
10ca0 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
10cb0 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
10cc0 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
10cd0 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
10ce0 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
10cf0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
10d00 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
10d10 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
10d20 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10d30 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
10d40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10d50 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
10d60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
10d70 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
10d80 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
10d90 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
10da0 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
10db0 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
10dc0 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
10dd0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
10de0 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
10df0 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
10e00 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
10e10 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
10e20 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
10e30 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
10e40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10e50 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
10e60 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
10e70 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
10e80 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
10e90 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
10ea0 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
10eb0 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
10ec0 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
10ed0 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
10ee0 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
10ef0 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
10f00 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
10f10 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
10f20 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
10f30 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
10f40 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
10f50 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
10f60 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
10f70 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
10f80 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
10f90 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
10fa0 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
10fb0 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
10fc0 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
10fd0 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
10fe0 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
10ff0 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
11000 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
11010 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
11020 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
11030 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
11040 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
11050 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
11060 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
11070 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
11080 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
11090 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
110a0 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c  alloc, xRealloc,
110b0 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
110c0 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
110d0 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
110e0 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
110f0 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
11100 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
11110 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
11120 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
11130 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
11140 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
11150 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
11160 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
11170 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
11180 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
11190 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  dup..**.** xSize
111a0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
111b0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
111c0 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
111d0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
111e0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
111f0 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
11200 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
11210 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
11220 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
11230 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
11240 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
11250 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
11260 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
11270 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
11280 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
11290 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
112a0 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
112b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
112c0 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
112d0 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
112e0 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
112f0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
11300 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
11310 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
11320 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
11330 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
11340 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
11350 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
11360 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
11370 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
11380 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
11390 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
113a0 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
113b0 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
113c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
113d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
113e0 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
113f0 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
11400 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
11410 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
11420 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
11430 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
11440 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
11450 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
11460 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
11470 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
11480 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20  allocator.  For 
11490 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
114a0 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
114b0 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
114c0 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
114d0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
114e0 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
114f0 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
11500 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
11510 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
11520 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
11530 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
11540 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
11550 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
11560 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
11570 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
11580 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
11590 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
115a0 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
115b0 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
115c0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
115d0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
115e0 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
115f0 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
11600 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
11610 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
11620 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
11630 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
11640 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
11650 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
11660 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
11670 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
11680 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
11690 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
116a0 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
116b0 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
116c0 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
116d0 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
116e0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
116f0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
11700 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
11710 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
11720 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11730 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
11740 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
11750 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
11760 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
11770 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
11780 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
11790 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
117a0 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
117b0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
117c0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
117d0 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
117e0 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
117f0 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
11800 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
11810 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
11820 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
11830 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
11840 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
11850 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
11860 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
11870 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
11880 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
11890 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
118a0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
118b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
118c0 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
118d0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
118e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
118f0 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
11900 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
11910 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
11920 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
11930 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
11940 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
11950 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
11960 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
11970 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
11980 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
11990 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
119a0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
119b0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
119c0 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
119d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
119e0 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
119f0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
11a00 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
11a10 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
11a20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
11a30 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
11a40 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
11a50 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
11a60 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
11a70 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
11a80 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
11a90 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
11aa0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
11ab0 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
11ac0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
11ad0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
11ae0 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
11af0 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
11b00 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
11b10 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
11b20 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
11b30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11b40 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
11b50 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
11b60 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
11b70 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
11b80 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
11b90 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
11ba0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
11bb0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
11bc0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
11bd0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
11be0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
11bf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
11c00 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11c10 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
11c20 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11c30 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
11c40 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
11c50 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
11c60 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
11c70 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
11c80 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
11c90 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
11ca0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
11cb0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
11cc0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
11cd0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
11ce0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
11cf0 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
11d00 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
11d10 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
11d20 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
11d30 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
11d40 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
11d50 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
11d60 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
11d70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11d80 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
11d90 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
11da0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
11db0 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
11dc0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
11dd0 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
11de0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
11df0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
11e00 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
11e10 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
11e20 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
11e30 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
11e40 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
11e50 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
11e60 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
11e70 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
11e80 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
11e90 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
11ea0 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
11eb0 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
11ec0 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
11ed0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11ee0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
11ef0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
11f00 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11f10 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
11f20 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
11f30 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
11f40 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
11f50 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
11f60 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
11f70 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
11f80 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
11f90 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
11fa0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
11fb0 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
11fc0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
11fd0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
11fe0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
11ff0 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
12000 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
12010 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12020 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
12030 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
12040 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
12050 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
12060 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
12070 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
12080 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
12090 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
120a0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
120b0 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
120c0 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
120d0 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
120e0 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
120f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12100 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
12110 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
12120 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
12130 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
12140 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
12150 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
12160 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
12170 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
12180 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
12190 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
121a0 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
121b0 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
121c0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
121d0 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
121e0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
121f0 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
12200 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
12210 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
12220 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
12230 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
12240 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
12250 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
12260 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12270 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12280 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12290 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
122a0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
122b0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
122c0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
122d0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
122e0 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
122f0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
12300 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
12310 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12320 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
12330 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
12340 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
12350 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
12360 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
12370 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
12380 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12390 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
123a0 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
123b0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
123c0 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
123d0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
123e0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
123f0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
12400 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
12410 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12420 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
12430 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12440 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
12450 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
12460 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
12470 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
12480 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
12490 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
124a0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
124b0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
124c0 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
124d0 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
124e0 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
124f0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12500 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
12510 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
12520 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
12530 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
12540 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
12550 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
12560 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
12570 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
12580 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
12590 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
125a0 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
125b0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
125c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
125d0 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
125e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
125f0 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
12600 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
12610 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
12620 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12630 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12640 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12650 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12660 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12670 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12680 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
12690 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
126a0 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
126b0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
126c0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
126d0 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
126e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
126f0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
12700 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
12710 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
12720 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
12730 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
12740 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12750 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
12760 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12770 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
12780 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
12790 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f  _CONFIG_MALLOC o
127a0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
127b0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
127c0 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
127d0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
127e0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
127f0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12800 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
12810 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
12820 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
12830 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
12840 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12850 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
12860 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
12870 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
12880 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
12890 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
128a0 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
128b0 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
128c0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
128d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
128e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
128f0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
12900 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
12910 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
12920 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
12930 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
12940 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12950 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
12960 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
12970 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
12980 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
12990 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
129a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
129b0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
129c0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
129d0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
129e0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
129f0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12a00 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
12a10 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
12a20 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
12a30 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
12a40 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
12a50 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
12a60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12a70 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
12a80 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
12a90 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
12aa0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
12ab0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
12ac0 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
12ad0 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
12ae0 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
12af0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
12b00 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
12b10 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
12b20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
12b30 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12b40 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
12b50 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
12b60 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
12b70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
12b80 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12b90 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f  _MEMSTATUS optio
12ba0 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
12bb0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
12bc0 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65  int,.** interpre
12bd0 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
12be0 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
12bf0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
12c00 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a  collection of.**
12c10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12c20 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  on statistics. ^
12c30 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
12c40 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
12c50 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  cs are.** disabl
12c60 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ed, the followin
12c70 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
12c80 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
12c90 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
12ca0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
12cb0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
12cc0 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
12cd0 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12ce0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
12cf0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12d00 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
12d10 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
12d20 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
12d30 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  64()].**   </ul>
12d40 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
12d50 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
12d60 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
12d70 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
12d80 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
12d90 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
12da0 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
12db0 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
12dc0 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
12dd0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
12de0 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
12df0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
12e00 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
12e10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12e20 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51  SCRATCH]] <dt>SQ
12e30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
12e40 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
12e50 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
12e60 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69  FIG_SCRATCH opti
12e70 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
12e80 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
12e90 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  fer.** that SQLi
12ea0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73  te can use for s
12eb0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
12ec0 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65  ^(There are thre
12ed0 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74  e arguments.** t
12ee0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
12ef0 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e  SCRATCH:  A poin
12f00 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
12f10 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
12f20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
12f30 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
12f40 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
12f50 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
12f60 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
12f70 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
12f80 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
12f90 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
12fa0 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
12fb0 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a  ations (N).)^.**
12fc0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12fd0 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
12fe0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
12ff0 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
13000 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
13010 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
13020 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
13030 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d  e will not use m
13040 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72  ore than one scr
13050 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
13060 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c   thread..** ^SQL
13070 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72  ite will never r
13080 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68  equest a scratch
13090 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20   buffer that is 
130a0 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74  more than 6.** t
130b0 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
130c0 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20  e page size..** 
130d0 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
130e0 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
130f0 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
13100 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
13110 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
13120 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
13130 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
13140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
13150 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
13160 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
13170 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
13180 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  p>.** ^When the 
13190 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76  application prov
131a0 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20  ides any amount 
131b0 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  of scratch memor
131c0 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54  y using.** SQLIT
131d0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
131e0 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20  , SQLite avoids 
131f0 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67  unnecessary larg
13200 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
13210 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61  lloc|heap alloca
13220 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20  tions]..** This 
13230 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e  can help [Robson
13240 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d   proof|prevent m
13250 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13260 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74   failures] due t
13270 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65  o heap.** fragme
13280 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d  ntation in low-m
13290 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73  emory embedded s
132a0 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  ystems..** </dd>
132b0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
132c0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
132d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
132e0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
132f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13300 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
13310 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20  AGECACHE option 
13320 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
13330 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
13340 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
13350 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20  can use for the 
13360 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
13370 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
13380 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63  ault page.** cac
13390 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
133a0 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
133b0 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
133c0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
133d0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
133e0 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
133f0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
13400 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
13410 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
13420 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 0a  CONFIG_PCACHE2].
13430 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
13440 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65   option..** ^The
13450 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
13460 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
13470 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
13480 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a  E: A pointer to.
13490 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  ** 8-byte aligne
134a0 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  d.** memory, the
134b0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
134c0 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
134d0 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
134e0 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
134f0 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
13500 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
13510 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
13520 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
13530 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
13540 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
13550 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73  nd 65536) plus s
13560 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20  ome extra bytes 
13570 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
13580 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e   header.  ^The n
13590 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62  umber of extra b
135a0 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74  ytes needed by t
135b0 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a  he page header.*
135c0 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
135d0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53  ned using the [S
135e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
135f0 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f  CHE_HDRSZ] optio
13600 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  n .** to [sqlite
13610 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20  3_config()]..** 
13620 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
13630 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
13640 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
13650 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72  * for the sz par
13660 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72  ameter to be lar
13670 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61  ger than necessa
13680 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ry.  The first.*
13690 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
136a0 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  d pointer to an 
136b0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
136c0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74  lock of memory t
136d0 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61  hat.** is at lea
136e0 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
136f0 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69   memory, otherwi
13700 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  se subsequent be
13710 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
13720 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69  efined..** ^SQLi
13730 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
13740 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
13750 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
13760 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
13770 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
13780 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
13790 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
137a0 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
137b0 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
137c0 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
137d0 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
137e0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
137f0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
13800 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
13810 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
13820 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13830 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
13840 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
13850 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ace.</dd>.**.** 
13860 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13870 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
13880 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
13890 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
138a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
138b0 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  AP option specif
138c0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
138d0 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74  ory buffer .** t
138e0 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
138f0 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
13900 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
13910 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
13920 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f  ds.** beyond tho
13930 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  se provided for 
13940 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
13950 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a  G_SCRATCH] and.*
13960 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
13970 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
13980 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
13990 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69  IG_HEAP option i
139a0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
139b0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
139c0 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65  mpiled.** with e
139d0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
139e0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
139f0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
13a00 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74  MEMSYS5] and ret
13a10 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
13a20 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65  ERROR] if invoke
13a30 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20  d otherwise..** 
13a40 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
13a50 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
13a60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
13a70 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61  :.** An 8-byte a
13a80 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
13a90 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
13aa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
13ab0 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
13ac0 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
13ad0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
13ae0 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
13af0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
13b00 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
13b10 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
13b20 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
13b30 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
13b40 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
13b50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
13b60 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
13b70 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
13b80 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
13b90 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
13ba0 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
13bb0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
13bc0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
13bd0 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
13be0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  ot NULL then the
13bf0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
13c00 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
13c10 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
13c20 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
13c30 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
13c40 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
13c50 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
13c60 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
13c70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
13c80 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
13c90 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
13ca0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
13cb0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
13cc0 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
13cd0 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
13ce0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13cf0 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
13d00 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
13d10 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
13d20 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
13d30 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
13d40 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
13d50 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
13d60 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13d70 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
13d80 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
13d90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13da0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13db0 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
13dc0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13dd0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a  ment which is a.
13de0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
13df0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13e00 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13e10 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13e20 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
13e30 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c  ent specifies al
13e40 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
13e50 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
13e60 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a  es to be used.**
13e70 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75   in place the mu
13e80 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
13e90 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
13ea0 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
13eb0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
13ec0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
13ed0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13ee0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13ef0 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
13f00 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
13f10 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
13f20 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
13f30 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13f40 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13f50 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13f60 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13f70 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
13f80 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
13f90 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
13fa0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
13fb0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
13fc0 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
13fd0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
13fe0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13ff0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
14000 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
14010 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14020 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
14030 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
14040 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14050 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14060 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
14070 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14080 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
14090 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
140a0 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f  G_GETMUTEX optio
140b0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
140c0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
140d0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
140e0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
140f0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
14100 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
14110 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
14120 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
14130 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
14140 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
14150 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
14160 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
14170 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
14180 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
14190 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
141a0 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
141b0 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
141c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
141d0 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
141e0 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
141f0 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
14200 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
14210 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
14220 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
14230 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14240 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
14250 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
14260 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
14270 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
14280 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
14290 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
142a0 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
142b0 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
142c0 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
142d0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
142e0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
142f0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
14300 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14310 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
14320 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
14330 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
14340 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
14350 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14360 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14370 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14380 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
14390 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
143a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
143b0 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e  LOOKASIDE option
143c0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
143d0 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
143e0 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75  ine.** the defau
143f0 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61  lt size of looka
14400 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65  side memory on e
14410 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ach [database co
14420 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
14430 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14440 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
14450 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
14460 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
14470 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
14480 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
14490 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
144a0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
144b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
144c0 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   ^(SQLITE_CONFIG
144d0 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65  _LOOKASIDE.** se
144e0 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c  ts the <i>defaul
144f0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
14500 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
14510 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
14520 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20  SIDE].** option 
14530 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
14540 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
14550 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
14560 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
14570 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
14580 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
14590 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
145a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
145b0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
145c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
145d0 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
145e0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
145f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14600 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
14610 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14620 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
14630 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14640 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
14650 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
14660 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
14670 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
14680 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63  interface to a c
14690 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
146a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
146b0 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61  )^.** ^SQLite ma
146c0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
146d0 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  e [sqlite3_pcach
146e0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
146f0 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ct.</dd>.**.** [
14700 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
14710 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
14720 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14730 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
14740 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
14750 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14760 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
14770 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14780 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
14790 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
147a0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
147b0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
147c0 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
147d0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65   of.** the curre
147e0 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  nt page cache im
147f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
14800 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
14810 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14820 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14830 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14840 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
14850 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
14860 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
14870 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
14880 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
14890 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
148a0 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
148b0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
148c0 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
148d0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
148e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
148f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
14900 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
14910 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
14920 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
14930 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
14940 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
14950 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
14960 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
14970 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
14980 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
14990 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
149a0 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
149b0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
149c0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
149d0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
149e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
149f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
14a00 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
14a10 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
14a20 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
14a30 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
14a40 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
14a50 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
14a60 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
14a70 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
14a80 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
14a90 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
14aa0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
14ab0 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
14ac0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
14ad0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
14ae0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
14af0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
14b00 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
14b10 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
14b20 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
14b30 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
14b40 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
14b50 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
14b60 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
14b70 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
14b80 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
14b90 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
14ba0 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
14bb0 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
14bc0 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
14bd0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
14be0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
14bf0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
14c00 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
14c10 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
14c20 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
14c30 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
14c40 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
14c50 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
14c60 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
14c70 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
14c80 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
14c90 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
14ca0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
14cb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
14cc0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
14cd0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
14ce0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
14cf0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14d00 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
14d10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14d20 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68  _URI.** <dd>^(Th
14d30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14d40 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  URI option takes
14d50 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14d60 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a  nt of type int..
14d70 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  ** If non-zero, 
14d80 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
14d90 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
14da0 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
14db0 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
14dc0 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e  .** then URI han
14dd0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
14de0 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49  y disabled.)^ ^I
14df0 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
14e00 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e  s globally.** en
14e10 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
14e20 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b  ames passed to [
14e30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
14e40 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
14e50 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
14e60 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
14e70 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
14e80 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
14e90 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
14ea0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
14eb0 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
14ec0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
14ed0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
14ee0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
14ef0 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
14f00 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
14f10 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14f20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
14f30 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
14f40 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
14f50 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
14f60 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
14f70 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
14f80 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
14f90 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
14fa0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
14fb0 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
14fc0 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
14fd0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
14fe0 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
14ff0 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
15000 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
15010 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
15020 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
15030 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
15040 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
15050 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
15060 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
15070 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15080 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
15090 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
150a0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
150b0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
150c0 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SCAN option take
150d0 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
150e0 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77  er.** argument w
150f0 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
15100 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
15110 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
15120 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a  ble or disable.*
15130 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  * the use of cov
15140 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
15150 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
15160 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
15170 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54  optimizer..** ^T
15180 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
15190 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
151a0 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
151b0 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
151c0 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
151d0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
151e0 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
151f0 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
15200 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
15210 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
15220 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
15230 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
15240 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
15250 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
15260 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
15270 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
15280 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
15290 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
152a0 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
152b0 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  * when the optim
152c0 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
152d0 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
152e0 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
152f0 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
15300 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
15310 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
15320 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
15330 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
15340 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
15350 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
15360 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
15370 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15380 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
15390 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
153a0 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
153b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
153c0 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
153d0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
153e0 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
153f0 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
15400 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
15410 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
15420 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
15430 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
15440 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
15450 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
15460 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
15470 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
15480 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
15490 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
154a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
154b0 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
154c0 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
154d0 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
154e0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
154f0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
15500 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
15510 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
15520 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
15530 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15540 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
15550 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
15560 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
15570 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
15580 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
15590 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
155a0 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
155b0 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
155c0 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
155d0 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
155e0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
155f0 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
15600 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
15610 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
15620 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
15630 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
15640 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
15650 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
15660 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
15670 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15680 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
15690 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
156a0 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
156b0 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
156c0 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
156d0 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
156e0 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
156f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
15700 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
15710 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
15720 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15730 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
15740 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
15750 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
15760 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
15770 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
15780 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
15790 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
157a0 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
157b0 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
157c0 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
157d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
157e0 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
157f0 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
15800 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
15810 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
15820 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
15830 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
15840 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
15850 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
15860 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
15870 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
15880 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
15890 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
158a0 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
158b0 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
158c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
158d0 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
158e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
158f0 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
15900 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  >^SQLITE_CONFIG_
15910 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
15920 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
15930 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
15940 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
15950 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
15960 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
15970 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
15980 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
15990 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
159a0 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
159b0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
159c0 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  ize limit..** ^T
159d0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
159e0 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  ng can be overri
159f0 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74  dden by each dat
15a00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15a10 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72   using.** either
15a20 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61   the [PRAGMA mma
15a30 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c  p_size] command,
15a40 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65   or by using the
15a50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
15a60 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
15a70 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68  e control.  ^(Th
15a80 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
15a90 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77  d mmap size.** w
15aa0 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20  ill be silently 
15ab0 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63  truncated if nec
15ac0 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69  essary so that i
15ad0 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65  t does not excee
15ae0 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d the.** compile
15af0 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
15b00 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
15b10 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
15b20 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
15b30 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15b40 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
15b50 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
15b60 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
15b70 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
15b80 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
15b90 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
15ba0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
15bb0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ult..**.** [[SQL
15bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15bd0 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  _HEAPSIZE]].** <
15be0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15bf0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a  _WIN32_HEAPSIZE.
15c00 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15c10 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15c20 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20  HEAPSIZE option 
15c30 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
15c40 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a  e if SQLite is.*
15c50 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57  * compiled for W
15c60 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20  indows with the 
15c70 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41  [SQLITE_WIN32_MA
15c80 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOC] pre-proces
15c90 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66  sor macro.** def
15ca0 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f  ined. ^SQLITE_CO
15cb0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15cc0 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62  IZE takes a 32-b
15cd0 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
15ce0 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61  ger value.** tha
15cf0 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
15d00 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
15d10 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70  the created heap
15d20 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15d30 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
15d40 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  DRSZ]].** <dt>SQ
15d50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15d60 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e  HE_HDRSZ.** <dd>
15d70 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15d80 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
15d90 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15da0 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
15db0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
15dc0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
15dd0 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69  ger and writes i
15de0 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
15df0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
15e00 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65  xtra.** bytes pe
15e10 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20  r page required 
15e20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e  for each page in
15e30 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
15e40 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
15e50 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74  he amount of ext
15e60 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65  ra space require
15e70 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70  d can change dep
15e80 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
15e90 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65  mpiler,.** targe
15ea0 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20  t platform, and 
15eb0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a  SQLite version..
15ec0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15ed0 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a  ONFIG_PMASZ]].**
15ee0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15ef0 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e  IG_PMASZ.** <dd>
15f00 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15f10 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20  IG_PMASZ option 
15f20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
15f30 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
15f40 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  * is an unsigned
15f50 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74   integer and set
15f60 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50  s the "Minimum P
15f70 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65  MA Size" for the
15f80 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a   multithreaded.*
15f90 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74  * sorter to that
15fa0 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64   integer.  The d
15fb0 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50  efault minimum P
15fc0 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62  MA Size is set b
15fd0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
15fe0 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63  _SORTER_PMASZ] c
15ff0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16000 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73  on.  New threads
16010 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a   are launched.**
16020 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f   to help with so
16030 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68  rt operations wh
16040 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  en multithreaded
16050 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65   sorting.** is e
16060 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68  nabled (using th
16070 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64  e [PRAGMA thread
16080 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20  s] command) and 
16090 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  the amount of co
160a0 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73  ntent.** to be s
160b0 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68  orted exceeds th
160c0 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65  e page size time
160d0 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66  s the minimum of
160e0 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   the.** [PRAGMA 
160f0 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74  cache_size] sett
16100 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c  ing and this val
16110 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ue..** </dl>.*/.
16120 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16130 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
16140 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
16150 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16160 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
16170 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
16180 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16190 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
161a0 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
161b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
161c0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
161d0 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
161e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
161f0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16200 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
16210 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
16220 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
16230 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
16250 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
16260 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
16270 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
16280 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16290 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
162a0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
162b0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
162c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
162d0 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
162e0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
162f0 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
16300 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16310 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
16320 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
16330 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
16340 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
16350 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
16360 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
16370 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
16380 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16390 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
163a0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
163b0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
163c0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
163d0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
163e0 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
163f0 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
16400 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
16410 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
16420 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
16430 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16450 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
16460 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
16470 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16480 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
16490 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
164a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
164b0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
164c0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
164d0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
164e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
164f0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
16500 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16510 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16520 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
16530 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
16540 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
16550 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16560 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
16570 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
16580 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
16590 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
165a0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
165b0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
165c0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
165d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
165e0 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
165f0 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
16600 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
16610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
16620 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
16630 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
16640 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
16650 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16660 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
16670 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20  APSIZE      23  
16680 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
16690 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
166a0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
166b0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a  SZ        24  /*
166c0 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65   int *psz */.#de
166d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
166e0 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20  IG_PMASZ        
166f0 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e         25  /* un
16700 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61  signed int szPma
16710 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
16720 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
16730 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
16740 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
16750 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
16760 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
16770 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
16780 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16790 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
167a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
167b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
167c0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
167d0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
167e0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
167f0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
16800 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
16810 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
16820 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
16830 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
16840 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16850 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
16860 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
16870 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
16880 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
16890 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
168a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
168b0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
168c0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
168d0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
168e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
168f0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
16900 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
16910 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
16920 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
16930 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
16940 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
16950 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
16960 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
16970 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
16980 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
16990 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
169a0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
169b0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
169c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
169d0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
169e0 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
169f0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
16a00 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
16a10 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
16a20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
16a30 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
16a40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
16a50 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
16a60 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
16a70 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
16a80 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
16a90 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
16aa0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
16ab0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
16ac0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
16ad0 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
16ae0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
16af0 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
16b00 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
16b10 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
16b20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
16b30 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
16b40 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
16b50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
16b60 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
16b70 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
16b80 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
16b90 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
16ba0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
16bb0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
16bc0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
16bd0 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
16be0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
16bf0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
16c00 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
16c10 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
16c20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
16c30 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
16c40 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
16c50 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
16c60 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
16c70 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
16c80 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
16c90 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
16ca0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
16cb0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16cc0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
16cd0 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
16ce0 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
16cf0 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
16d00 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
16d10 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
16d20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
16d30 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
16d40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
16d50 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
16d60 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
16d70 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
16d80 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
16d90 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
16da0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
16db0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
16dc0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
16dd0 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
16de0 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
16df0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
16e00 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
16e10 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
16e20 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
16e30 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
16e40 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
16e50 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
16e60 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
16e70 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
16e80 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
16e90 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
16ea0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
16eb0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
16ec0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
16ed0 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
16ee0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
16ef0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
16f00 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
16f10 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
16f20 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
16f30 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
16f40 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
16f50 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
16f60 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
16f70 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
16f80 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
16f90 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
16fa0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16fb0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
16fc0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
16fd0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
16fe0 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
16ff0 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
17000 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
17010 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
17020 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
17030 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
17040 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17050 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17060 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
17070 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
17080 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
17090 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
170a0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
170b0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
170c0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
170d0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
170e0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
170f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
17100 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
17110 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
17120 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
17130 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
17140 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
17150 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17160 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
17170 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
17180 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
17190 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
171a0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
171b0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
171c0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
171d0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
171e0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
171f0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
17200 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
17210 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
17220 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
17230 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
17240 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
17250 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
17260 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
17270 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
17280 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
17290 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
172a0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
172b0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
172c0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
172d0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
172e0 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
172f0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
17300 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
17310 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
17320 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17330 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
17340 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
17350 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
17360 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
17370 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
17380 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
17390 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
173a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
173b0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
173c0 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20         1001  /* 
173d0 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
173e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
173f0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
17400 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f  FKEY     1002  /
17410 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
17420 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
17430 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
17440 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69  GGER  1003  /* i
17450 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
17460 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
17470 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
17480 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
17490 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  odes.** METHOD: 
174a0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
174b0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
174c0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
174d0 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
174e0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
174f0 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
17500 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
17510 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
17520 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
17530 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
17540 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
17550 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
17560 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
17570 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ity..*/.SQLITE_A
17580 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
17590 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78  DCALL sqlite3_ex
175a0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
175b0 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
175c0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
175d0 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
175e0 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20  Insert Rowid.** 
175f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
17600 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
17610 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65  y in most SQLite
17620 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20   tables (except 
17630 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  for [WITHOUT ROW
17640 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68  ID] tables).** h
17650 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
17660 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
17670 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
17680 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
17690 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
176a0 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
176b0 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
176c0 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
176d0 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
176e0 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
176f0 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
17700 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
17710 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
17720 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
17730 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
17740 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
17750 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
17760 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
17770 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
17780 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
17790 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
177a0 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
177b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73  ^The sqlite3_las
177c0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
177d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
177e0 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
177f0 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20  of the .** most 
17800 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
17810 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
17820 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72  a rowid table or
17830 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
17840 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20  .** on database 
17850 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a  connection D..**
17860 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b   ^Inserts into [
17870 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
17880 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65  ables are not re
17890 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e  corded..** ^If n
178a0 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
178b0 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69  SERT]s into rowi
178c0 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65  d tables.** have
178d0 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
178e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
178f0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a  onnection D, .**
17900 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61   then sqlite3_la
17910 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17920 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  D) returns zero.
17930 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
17940 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
17950 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
17960 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
17970 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
17980 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
17990 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
179a0 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
179b0 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
179c0 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
179d0 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
179e0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
179f0 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
17a00 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
17a10 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
17a20 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
17a30 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
17a40 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
17a50 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
17a60 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
17a70 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
17a80 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
17a90 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
17aa0 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
17ab0 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
17ac0 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
17ad0 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
17ae0 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
17af0 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
17b00 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
17b10 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
17b20 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
17b30 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
17b40 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
17b50 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
17b60 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
17b70 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
17b80 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
17b90 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
17ba0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
17bb0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
17bc0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
17bd0 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
17be0 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
17bf0 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
17c00 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
17c10 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
17c20 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
17c30 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
17c40 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
17c50 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
17c60 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
17c70 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
17c80 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
17c90 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
17ca0 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
17cb0 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
17cc0 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
17cd0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
17ce0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
17cf0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
17d00 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
17d10 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
17d20 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
17d30 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
17d40 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
17d50 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
17d60 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
17d70 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
17d80 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
17d90 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
17da0 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
17db0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17dc0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
17dd0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
17de0 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
17df0 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
17e00 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
17e10 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
17e20 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
17e30 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
17e40 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
17e50 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
17e60 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
17e70 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
17e80 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
17e90 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
17ea0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
17eb0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
17ec0 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
17ed0 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
17ee0 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
17ef0 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
17f00 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
17f10 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
17f20 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  owid]..*/.SQLITE
17f30 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
17f40 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  64 SQLITE_STDCAL
17f50 4c 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  L sqlite3_last_i
17f60 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
17f70 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
17f80 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
17f90 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
17fa0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
17fb0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
17fc0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
17fd0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
17fe0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
17ff0 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20  ified, inserted 
18000 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
18010 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
18020 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
18030 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
18040 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
18050 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  nt on the databa
18060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  se connection sp
18070 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
18080 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  nly parameter..*
18090 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  * ^Executing any
180a0 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
180b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
180c0 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  s not modify the
180d0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
180e0 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
180f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  ion..**.** ^Only
18100 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69   changes made di
18110 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e  rectly by the IN
18120 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
18130 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
18140 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
18150 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63  ed - auxiliary c
18160 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
18170 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
18180 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a   | triggers], .*
18190 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
181a0 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c  ctions] or [REPL
181b0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
181c0 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e  resolution are n
181d0 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
181e0 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
181f0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
18200 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a  tercepted by .**
18210 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
18220 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f  gger | INSTEAD O
18230 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20  F triggers] are 
18240 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68  not counted. ^Th
18250 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75  e value .** retu
18260 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
18270 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69  changes() immedi
18280 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49  ately after an I
18290 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
182a0 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74   .** DELETE stat
182b0 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76  ement run on a v
182c0 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65  iew is always ze
182d0 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ro. Only changes
182e0 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a   made to real .*
182f0 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75  * tables are cou
18300 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  nted..**.** Thin
18310 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70  gs are more comp
18320 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73  licated if the s
18330 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
18340 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
18350 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61  executed while a
18360 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
18370 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69   is running. Thi
18380 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20  s may happen if 
18390 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  the.** program u
183a0 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73  ses the [changes
183b0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
183c0 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68  , or if some oth
183d0 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  er callback.** f
183e0 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  unction invokes 
183f0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18400 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65  ) directly. Esse
18410 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20  ntially:.** .** 
18420 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  <ul>.**   <li> ^
18430 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67  (Before entering
18440 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
18450 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  am the value ret
18460 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
18470 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67     sqlite3_chang
18480 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
18490 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68   saved. After th
184a0 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
184b0 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73  m .**        has
184c0 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f   finished, the o
184d0 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73  riginal value is
184e0 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20   restored.)^.** 
184f0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74  .**   <li> ^(Wit
18500 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72  hin a trigger pr
18510 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52  ogram each INSER
18520 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45  T, UPDATE and DE
18530 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20  LETE .**        
18540 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74  statement sets t
18550 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
18560 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
18570 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
18580 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f    upon completio
18590 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20  n as normal. Of 
185a0 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c  course, this val
185b0 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c  ue will not incl
185c0 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61  ude .**        a
185d0 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f  ny changes perfo
185e0 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67  rmed by sub-trig
185f0 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c  gers, as the sql
18600 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
18610 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20  **        value 
18620 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e  will be saved an
18630 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72  d restored after
18640 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65   each sub-trigge
18650 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20  r has run.)^.** 
18660 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68  </ul>.** .** ^Th
18670 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
18680 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53   the changes() S
18690 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20  QL function (or 
186a0 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64  similar) is used
186b0 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
186c0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
186d0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
186e0 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
186f0 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74  gger, it .** ret
18700 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61  urns the value a
18710 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63  s set when the c
18720 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  alling statement
18730 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67   began executing
18740 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75  ..** ^If it is u
18750 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  sed by the secon
18760 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  d or subsequent 
18770 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77  such statement w
18780 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
18790 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65  .** program, the
187a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
187b0 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d  reflects the num
187c0 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
187d0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
187e0 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c  previous INSERT,
187f0 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
18800 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
18810 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  in the same trig
18820 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ger..**.** See a
18830 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
18840 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
18850 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
18860 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
18870 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
18880 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
18890 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
188a0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
188b0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
188c0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
188d0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
188e0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
188f0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
18900 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
18910 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
18920 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
18930 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
18940 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
18950 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
18960 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
18970 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18980 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
18990 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
189a0 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
189b0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
189c0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
189d0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
189e0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  n returns the to
189f0 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  tal number of ro
18a00 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64  ws inserted, mod
18a10 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  ified or.** dele
18a20 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45  ted by all [INSE
18a30 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72  RT], [UPDATE] or
18a40 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
18a50 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a  ents completed.*
18a60 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  * since the data
18a70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18a80 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c  was opened, incl
18a90 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63  uding those exec
18aa0 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  uted as.** part 
18ab0 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  of trigger progr
18ac0 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20  ams. ^Executing 
18ad0 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
18ae0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  f SQL statement.
18af0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65  ** does not affe
18b00 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ct the value ret
18b10 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
18b20 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
18b30 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65  ..** .** ^Change
18b40 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  s made as part o
18b50 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  f [foreign key a
18b60 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c  ctions] are incl
18b70 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63  uded in the.** c
18b80 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20  ount, but those 
18b90 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20  made as part of 
18ba0 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
18bb0 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
18bc0 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67  e.** not. ^Chang
18bd0 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
18be0 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
18bf0 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20  d by INSTEAD OF 
18c00 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65  triggers .** are
18c10 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   not counted..**
18c20 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68   .** See also th
18c30 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
18c40 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
18c50 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
18c60 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
18c70 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
18c80 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
18c90 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
18ca0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
18cb0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
18cc0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
18cd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18ce0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
18cf0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
18d00 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
18d10 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
18d20 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
18d30 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
18d40 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
18d50 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
18d60 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
18d70 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
18d80 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
18d90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18da0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
18db0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
18dc0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
18dd0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
18de0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
18df0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
18e00 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
18e10 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
18e20 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
18e30 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
18e40 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
18e50 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
18e60 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
18e70 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
18e80 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
18e90 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
18ea0 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
18eb0 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
18ec0 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
18ed0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
18ee0 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
18ef0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
18f00 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
18f10 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
18f20 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
18f30 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
18f40 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
18f50 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
18f60 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
18f70 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
18f80 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
18f90 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
18fa0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
18fb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
18fc0 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
18fd0 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
18fe0 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
18ff0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
19000 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
19010 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
19020 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
19030 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
19040 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
19050 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
19060 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
19070 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
19080 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
19090 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
190a0 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
190b0 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
190c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
190d0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
190e0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
190f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
19100 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
19110 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
19120 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
19130 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
19140 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
19150 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
19160 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
19170 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
19180 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
19190 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
191a0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
191b0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
191c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
191d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
191e0 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
191f0 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
19200 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
19210 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
19220 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
19230 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
19240 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
19250 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
19260 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
19270 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
19280 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
19290 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
192a0 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
192b0 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
192c0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
192d0 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
192e0 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
192f0 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
19300 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
19310 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
19320 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
19330 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
19340 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
19350 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
19360 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
19370 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
19380 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
19390 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
193a0 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
193b0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
193c0 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
193d0 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
193e0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
193f0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
19400 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
19410 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
19420 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
19430 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
19440 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
19450 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
19460 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
19470 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
19480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19490 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
194a0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
194b0 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
194c0 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
194d0 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
194e0 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  happen..*/.SQLIT
194f0 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
19500 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
19510 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
19520 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
19530 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
19540 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
19550 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
19560 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
19570 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
19580 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
19590 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
195a0 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
195b0 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
195c0 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
195d0 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
195e0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
195f0 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
19600 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
19610 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
19620 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
19630 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
19640 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
19650 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
19660 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
19670 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
19680 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
19690 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
196a0 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
196b0 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
196c0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
196d0 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
196e0 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
196f0 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
19700 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
19710 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
19720 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
19730 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
19740 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
19750 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
19760 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
19770 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
19780 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
19790 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
197a0 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
197b0 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
197c0 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
197d0 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
197e0 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
197f0 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
19800 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
19810 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
19820 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
19830 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
19840 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
19850 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
19860 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
19870 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
19880 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
19890 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
198a0 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
198b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
198c0 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
198d0 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
198e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
198f0 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
19900 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
19910 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
19920 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
19930 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
19940 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
19950 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
19960 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
19970 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
19980 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
19990 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
199a0 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
199b0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
199c0 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
199d0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
199e0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
199f0 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
19a00 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
19a10 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
19a20 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
19a30 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
19a40 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
19a50 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
19a60 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
19a70 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
19a80 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
19a90 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
19aa0 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
19ab0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
19ac0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
19ad0 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
19ae0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
19af0 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
19b00 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
19b10 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
19b20 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
19b30 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
19b40 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
19b50 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
19b60 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
19b70 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
19b80 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
19b90 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
19ba0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
19bb0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
19bc0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
19bd0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  L sqlite3_comple
19be0 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
19bf0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
19c00 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
19c10 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
19c20 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
19c30 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57  Y Errors.** KEYW
19c40 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64  ORDS: {busy-hand
19c50 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62  ler callback} {b
19c60 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20  usy handler}.** 
19c70 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
19c80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
19c90 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
19ca0 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73  D,X,P) routine s
19cb0 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
19cc0 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61  unction X.** tha
19cd0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
19ce0 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
19cf0 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61   P whenever.** a
19d00 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
19d10 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61  e to access a da
19d20 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73  tabase table ass
19d30 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
19d40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19d50 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f  tion] D when ano
19d60 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
19d70 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68  r process has th
19d80 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a  e table locked..
19d90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
19da0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e  usy_handler() in
19db0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
19dc0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20  to implement.** 
19dd0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
19de0 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52  meout()] and [PR
19df0 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
19e00 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  t]..**.** ^If th
19e10 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
19e20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
19e30 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69  QLITE_BUSY].** i
19e40 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
19e50 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
19e60 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
19e70 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
19e80 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
19e90 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
19ea0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
19eb0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
19ec0 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
19ed0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
19ee0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
19ef0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
19f00 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
19f10 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
19f20 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
19f30 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
19f40 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
19f50 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
19f60 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
19f70 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
19f80 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
19f90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
19fa0 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
19fb0 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
19fc0 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70  * been invoked p
19fd0 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68  reviously for th
19fe0 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65  e same locking e
19ff0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
1a000 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
1a010 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
1a020 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
1a030 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
1a040 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
1a050 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
1a060 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72  QLITE_BUSY] is r
1a070 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68  eturned.** to th
1a080 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a  e application..*
1a090 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
1a0a0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1a0b0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
1a0c0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
1a0d0 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74  made to access t
1a0e0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1a0f0 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
1a100 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
1a110 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
1a120 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
1a130 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
1a140 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
1a150 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
1a160 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
1a170 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
1a180 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
1a190 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
1a1a0 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
1a1b0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
1a1c0 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
1a1d0 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
1a1e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
1a1f0 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  Y].** to the app
1a200 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64  lication instead
1a210 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
1a220 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65   .** busy handle
1a230 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
1a240 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
1a250 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
1a260 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
1a270 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
1a280 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
1a290 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
1a2a0 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
1a2b0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
1a2c0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
1a2d0 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
1a2e0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
1a2f0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
1a300 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
1a310 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
1a320 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
1a330 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
1a340 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1a350 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
1a360 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
1a370 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
1a380 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1a390 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
1a3a0 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
1a3b0 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
1a3c0 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
1a3d0 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
1a3e0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
1a3f0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
1a400 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
1a410 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
1a420 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
1a430 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
1a440 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
1a450 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
1a460 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
1a470 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
1a480 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
1a490 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1a4a0 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
1a4b0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1a4c0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
1a4d0 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
1a4e0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1a4f0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1a500 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
1a510 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
1a520 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a530 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
1a540 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
1a550 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
1a560 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
1a570 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
1a580 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
1a590 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1a5a0 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75  t()].** or evalu
1a5b0 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75  ating [PRAGMA bu
1a5c0 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69  sy_timeout=N] wi
1a5d0 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  ll change the.**
1a5e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e   busy handler an
1a5f0 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79  d thus clear any
1a600 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1a610 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1a620 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
1a630 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
1a640 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
1a650 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
1a660 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
1a670 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1a680 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1a690 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68  handler.  In oth
1a6a0 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65  er words,.** the
1a6b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1a6c0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20   not reentrant. 
1a6d0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
1a6e0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
1a6f0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
1a700 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
1a710 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
1a720 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
1a730 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1a740 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
1a750 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1a760 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1a770 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c   handler..*/.SQL
1a780 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
1a790 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1a7a0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1a7b0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
1a7c0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
1a7d0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1a7e0 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
1a7f0 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48   Timeout.** METH
1a800 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1a810 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1a820 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
1a830 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
1a840 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
1a850 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
1a860 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
1a870 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
1a880 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
1a890 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
1a8a0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
1a8b0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
1a8c0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
1a8d0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1a8e0 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
1a8f0 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
1a900 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
1a910 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1a920 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
1a930 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
1a940 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
1a950 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
1a960 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
1a970 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
1a980 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
1a990 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
1a9a0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
1a9b0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
1a9c0 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
1a9d0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
1a9e0 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
1a9f0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1aa00 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1aa10 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
1aa20 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1aa30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1aa40 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65  ion] at any give
1aa50 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
1aa60 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1aa70 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
1aa80 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
1aa90 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1aaa0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
1aab0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
1aac0 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
1aad0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1aae0 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a   cleared.)^.**.*
1aaf0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52  * See also:  [PR
1ab00 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1ab10 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t].*/.SQLITE_API
1ab20 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1ab30 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79  ALL sqlite3_busy
1ab40 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1ab50 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1ab60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1ab70 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1ab80 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1ab90 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eries.** METHOD:
1aba0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
1abb0 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
1abc0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
1abd0 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
1abe0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1abf0 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
1ac00 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1ac10 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
1ac20 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
1ac30 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
1ac40 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
1ac50 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
1ac60 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
1ac70 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1ac80 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
1ac90 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
1aca0 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
1acb0 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
1acc0 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
1acd0 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
1ace0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
1acf0 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
1ad00 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
1ad10 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
1ad20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
1ad30 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
1ad40 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
1ad50 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1ad60 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
1ad70 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
1ad80 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
1ad90 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
1ada0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
1adb0 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
1adc0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1add0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
1ade0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
1adf0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
1ae00 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1ae10 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
1ae20 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
1ae30 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
1ae40 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
1ae50 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
1ae60 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
1ae70 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1ae80 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
1ae90 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
1aea0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
1aeb0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
1aec0 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
1aed0 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
1aee0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
1aef0 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
1af00 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
1af10 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
1af20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
1af30 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1af40 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
1af50 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
1af60 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1af70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1af80 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
1af90 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
1afa0 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
1afb0 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
1afc0 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
1afd0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
1afe0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
1aff0 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
1b000 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1b010 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1b020 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
1b030 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
1b040 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1b050 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
1b060 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
1b070 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1b080 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
1b090 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
1b0a0 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
1b0b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1b0c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1b0d0 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
1b0e0 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
1b0f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1b100 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
1b110 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
1b120 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
1b130 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
1b140 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
1b150 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
1b160 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1b170 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
1b180 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
1b190 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
1b1a0 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
1b1b0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
1b1c0 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
1b1d0 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
1b1e0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
1b1f0 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
1b200 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
1b210 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
1b220 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
1b230 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
1b240 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1b250 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b260 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
1b270 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1b280 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
1b290 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
1b2a0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
1b2b0 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
1b2c0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1b2d0 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
1b2e0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b2f0 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
1b300 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1b310 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
1b320 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b330 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
1b340 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
1b350 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
1b360 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
1b370 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1b380 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
1b390 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1b3a0 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
1b3b0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
1b3c0 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
1b3d0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
1b3e0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
1b3f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1b400 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
1b410 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
1b420 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
1b430 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
1b440 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
1b450 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
1b460 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1b470 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
1b480 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
1b490 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
1b4a0 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
1b4b0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
1b4c0 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
1b4d0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1b4e0 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
1b4f0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
1b500 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
1b510 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1b520 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
1b530 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
1b540 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
1b550 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1b560 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
1b570 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
1b580 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
1b590 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
1b5a0 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
1b5b0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
1b5c0 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
1b5d0 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
1b5e0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
1b5f0 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
1b600 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
1b610 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
1b620 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1b630 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1b640 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
1b650 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
1b660 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
1b670 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1b680 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
1b690 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
1b6a0 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
1b6b0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
1b6c0 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
1b6d0 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
1b6e0 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
1b6f0 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
1b700 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
1b710 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
1b720 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
1b730 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
1b740 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
1b750 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
1b760 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
1b770 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1b780 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
1b790 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
1b7a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1b7b0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1b7c0 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
1b7d0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
1b7e0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1b7f0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1b800 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1b810 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1b820 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
1b830 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
1b840 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1b850 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
1b860 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
1b870 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
1b880 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
1b890 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
1b8a0 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
1b8b0 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
1b8c0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1b8d0 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
1b8e0 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
1b8f0 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
1b900 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1b910 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
1b920 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
1b930 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
1b940 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
1b950 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1b960 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .);.SQLITE_API v
1b970 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
1b980 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  LL sqlite3_free_
1b990 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
1b9a0 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
1b9b0 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
1b9c0 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
1b9d0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1b9e0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1b9f0 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
1ba00 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
1ba10 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
1ba20 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
1ba30 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1ba40 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72  rary..** These r
1ba50 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61  outines understa
1ba60 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63  nd most of the c
1ba70 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74  ommon K&R format
1ba80 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a  ting options,.**
1ba90 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74   plus some addit
1baa0 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61  ional non-standa
1bab0 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61  rd formats, deta
1bac0 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e  iled below..** N
1bad0 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66  ote that some of
1bae0 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72   the more obscur
1baf0 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  e formatting opt
1bb00 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74  ions from recent
1bb10 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74  .** C-library st
1bb20 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74  andards are omit
1bb30 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d  ted from this im
1bb40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a  plementation..**
1bb50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1bb60 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
1bb70 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1bb80 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
1bb90 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
1bba0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
1bbb0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1bbc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
1bbd0 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1bbe0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1bbf0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1bc00 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1bc10 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1bc20 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1bc30 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1bc40 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1bc50 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1bc60 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
1bc70 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
1bc80 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
1bc90 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
1bca0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
1bcb0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1bcc0 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
1bcd0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
1bce0 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
1bcf0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1bd00 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
1bd10 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
1bd20 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
1bd30 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
1bd40 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1bd50 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
1bd60 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
1bd70 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
1bd80 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
1bd90 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
1bda0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
1bdb0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
1bdc0 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
1bdd0 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
1bde0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
1bdf0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
1be00 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
1be10 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
1be20 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
1be30 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
1be40 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
1be50 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
1be60 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
1be70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
1be80 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
1be90 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
1bea0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
1beb0 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
1bec0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
1bed0 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
1bee0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
1bef0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
1bf00 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
1bf10 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
1bf20 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
1bf30 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
1bf40 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
1bf50 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
1bf60 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
1bf70 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
1bf80 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
1bf90 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
1bfa0 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
1bfb0 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
1bfc0 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
1bfd0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1bfe0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
1bff0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
1c000 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
1c010 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
1c020 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
1c030 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
1c040 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
1c050 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
1c060 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
1c070 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1c080 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
1c090 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
1c0a0 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
1c0b0 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
1c0c0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
1c0d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c0e0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
1c0f0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
1c100 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
1c110 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1c120 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
1c130 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
1c140 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
1c150 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
1c160 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
1c170 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
1c180 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
1c190 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1c1a0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
1c1b0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
1c1c0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
1c1d0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
1c1e0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
1c1f0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22  re "%q", "%Q", "
1c200 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  %w" and "%z" opt
1c210 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
1c220 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
1c230 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
1c240 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
1c250 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
1c260 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
1c270 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
1c280 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
1c290 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
1c2a0 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
1c2b0 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
1c2c0 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
1c2d0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1c2e0 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
1c2f0 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
1c300 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
1c310 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
1c320 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
1c330 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
1c340 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
1c350 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
1c360 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
1c370 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
1c380 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
1c390 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
1c3a0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1c3b0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1c3c0 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
1c3d0 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
1c3e0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1c3f0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
1c400 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
1c410 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
1c420 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
1c430 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1c440 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1c450 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1c460 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1c470 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1c480 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
1c490 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1c4a0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1c4b0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1c4c0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1c4d0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1c4e0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1c4f0 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
1c500 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
1c510 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
1c520 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
1c530 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
1c540 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
1c550 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
1c560 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1c570 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1c580 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1c590 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
1c5a0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1c5b0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1c5c0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1c5d0 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
1c5e0 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
1c5f0 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
1c600 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
1c610 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
1c620 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
1c630 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1c640 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1c650 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1c660 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
1c670 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
1c680 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1c690 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
1c6a0 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
1c6b0 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
1c6c0 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
1c6d0 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
1c6e0 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
1c6f0 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
1c700 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
1c710 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
1c720 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
1c730 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
1c740 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
1c750 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
1c760 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
1c770 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
1c780 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1c790 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
1c7a0 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
1c7b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
1c7c0 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
1c7d0 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
1c7e0 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
1c7f0 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
1c800 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
1c810 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
1c820 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
1c830 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
1c840 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
1c850 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c860 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1c870 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1c880 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1c890 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
1c8a0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1c8b0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1c8c0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1c8d0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1c8e0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1c8f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1c900 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
1c910 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
1c920 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
1c930 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
1c940 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
1c950 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
1c960 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
1c970 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1c980 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d   ^(The "%w" form
1c990 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73  atting option is
1c9a0 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70   like "%q" excep
1c9b0 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74  t that it expect
1c9c0 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61  s to.** be conta
1c9d0 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62  ined within doub
1c9e0 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61  le-quotes instea
1c9f0 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74  d of single quot
1ca00 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73  es, and it.** es
1ca10 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65  capes the double
1ca20 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72  -quote character
1ca30 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1ca40 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20  single-quote.** 
1ca50 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68  character.)^  Th
1ca60 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e  e "%w" formattin
1ca70 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65  g option is inte
1ca80 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20  nded for safely 
1ca90 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62  inserting.** tab
1caa0 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61  le and column na
1cab0 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74  mes into a const
1cac0 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65  ructed SQL state
1cad0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ment..**.** ^(Th
1cae0 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
1caf0 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
1cb00 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
1cb10 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
1cb20 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
1cb30 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
1cb40 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
1cb50 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
1cb60 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
1cb70 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
1cb80 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
1cb90 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  ing.)^.*/.SQLITE
1cba0 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54  _API char *SQLIT
1cbb0 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f  E_CDECL sqlite3_
1cbc0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1cbd0 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  ar*,...);.SQLITE
1cbe0 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54  _API char *SQLIT
1cbf0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1cc00 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1cc10 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1cc20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1cc30 72 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20  r *SQLITE_CDECL 
1cc40 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1cc50 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1cc60 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51   char*, ...);.SQ
1cc70 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53  LITE_API char *S
1cc80 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1cc90 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1cca0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1ccb0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1ccc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ccd0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1cce0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1ccf0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1cd00 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1cd10 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1cd20 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1cd30 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1cd40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1cd50 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1cd60 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1cd70 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1cd80 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1cd90 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1cda0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1cdb0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1cdc0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1cdd0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1cde0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1cdf0 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1ce00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ce10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1ce20 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1ce30 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1ce40 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1ce50 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1ce60 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1ce70 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1ce80 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1ce90 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1cea0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1ceb0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1cec0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1ced0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1cee0 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1cef0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1cf00 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1cf10 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1cf20 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1cf30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1cf40 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1cf50 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
1cf60 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1cf70 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77  c64(N) routine w
1cf80 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a  orks just like.*
1cf90 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1cfa0 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  (N) except that 
1cfb0 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  N is an unsigned
1cfc0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1cfd0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1cfe0 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e  signed 32-bit in
1cff0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  teger..**.** ^Ca
1d000 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1d010 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1d020 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1d030 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1d040 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1d050 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1d060 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1d070 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1d080 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1d090 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1d0a0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1d0b0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1d0c0 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1d0d0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1d0e0 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1d0f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1d100 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1d110 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1d120 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1d130 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1d140 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1d150 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1d160 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1d170 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1d180 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1d190 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1d1a0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1d1b0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1d1c0 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1d1d0 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1d1e0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1d1f0 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1d200 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1d210 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1d220 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1d230 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1d240 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1d250 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1d260 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1d270 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1d280 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1d290 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1d2a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1d2b0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1d2c0 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1d2d0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1d2e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20  allocation X to 
1d2f0 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1d300 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
1d310 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  X parameter to s
1d320 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1d330 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ,N).** is a NULL
1d340 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1d350 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1d360 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1d370 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1d380 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20  lloc(N)..** ^If 
1d390 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
1d3a0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1d3b0 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20  oc(X,N) is zero 
1d3c0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1d3d0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1d3e0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1d3f0 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1d400 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1d410 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  X)..** ^sqlite3_
1d420 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1d430 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1d440 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1d450 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1d460 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1d470 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1d480 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
1d490 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ory is available
1d4a0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1d4b0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1d4c0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1d4d0 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1d4e0 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1d4f0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1d500 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1d510 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1d520 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1d530 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1d540 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74  alloc(X,N) and t
1d550 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1d560 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1d570 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1d580 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1d590 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
1d5a0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74  positive, then t
1d5b0 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f  he.** prior allo
1d5c0 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72  cation is not fr
1d5d0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1d5e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1d5f0 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  4(X,N) interface
1d600 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  s works the same
1d610 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   as.** sqlite3_r
1d620 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65  ealloc(X,N) exce
1d630 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36  pt that N is a 6
1d640 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  4-bit unsigned i
1d650 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1d660 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  * of a 32-bit si
1d670 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
1d680 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d  .** ^If X is a m
1d690 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d6a0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
1d6b0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1d6c0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  3_malloc(),.** s
1d6d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1d6e0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1d6f0 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  oc(), or sqlite3
1d700 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68  _realloc64(), th
1d710 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
1d720 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74  ize(X) returns t
1d730 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20  he size of that 
1d740 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d750 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  n in bytes..** ^
1d760 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1d770 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73  ed by sqlite3_ms
1d780 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20  ize(X) might be 
1d790 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
1d7a0 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
1d7b0 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65  es requested whe
1d7c0 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65  n X was allocate
1d7d0 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e  d.  ^If X is a N
1d7e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1d7f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1d800 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72  e(X) returns zer
1d810 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20  o.  If X points 
1d820 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61  to something tha
1d830 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20  t is not.** the 
1d840 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d  beginning of mem
1d850 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
1d860 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20  or if it points 
1d870 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a  to a formerly.**
1d880 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c   valid memory al
1d890 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61  location that ha
1d8a0 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64  s now been freed
1d8b0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
1d8c0 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ior.** of sqlite
1d8d0 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e  3_msize(X) is un
1d8e0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73  defined and poss
1d8f0 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ibly harmful..**
1d900 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1d910 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1d920 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71  te3_malloc(), sq
1d930 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1d940 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1d950 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69  oc64(), and sqli
1d960 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a  te3_realloc64().
1d970 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1d980 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1d990 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1d9a0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1d9b0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1d9c0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1d9d0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1d9e0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1d9f0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1da00 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1da10 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1da20 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1da30 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1da40 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1da50 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1da60 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1da70 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1da80 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1da90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1daa0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1dab0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1dac0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1dad0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1dae0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1daf0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1db00 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1db10 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1db20 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1db30 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1db40 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1db50 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1db60 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1db70 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1db80 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1db90 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1dba0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1dbb0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1dbc0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1dbd0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1dbe0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1dbf0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1dc00 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1dc10 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1dc20 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1dc30 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1dc40 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1dc50 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1dc60 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1dc70 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1dc80 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1dc90 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1dca0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1dcb0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1dcc0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1dcd0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1dce0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1dcf0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1dd00 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1dd10 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1dd20 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1dd30 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1dd40 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1dd50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1dd60 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1dd70 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1dd80 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1dd90 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1dda0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1ddb0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1ddc0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1ddd0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1dde0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1ddf0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1de00 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1de10 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1de20 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1de30 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  alloc()]..*/.SQL
1de40 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51  ITE_API void *SQ
1de50 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1de60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
1de70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1de80 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
1de90 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  L sqlite3_malloc
1dea0 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64(sqlite3_uint6
1deb0 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  4);.SQLITE_API v
1dec0 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
1ded0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ALL sqlite3_real
1dee0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1def0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1df00 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
1df10 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1df20 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
1df30 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  3_uint64);.SQLIT
1df40 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
1df50 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1df60 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53  3_free(void*);.S
1df70 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
1df80 33 5f 75 69 6e 74 36 34 20 53 51 4c 49 54 45 5f  3_uint64 SQLITE_
1df90 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1dfa0 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  msize(void*);../
1dfb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1dfc0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
1dfd0 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
1dfe0 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
1dff0 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
1e000 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
1e010 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
1e020 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
1e030 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
1e040 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1e050 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
1e060 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
1e070 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
1e080 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
1e090 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1e0a0 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
1e0b0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1e0c0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
1e0d0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1e0e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1e0f0 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
1e100 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
1e110 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
1e120 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
1e130 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1e140 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1e150 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
1e160 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
1e170 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
1e180 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1e190 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
1e1a0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1e1b0 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
1e1c0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
1e1d0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1e1e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1e1f0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1e200 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1e210 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
1e220 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
1e230 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
1e240 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
1e250 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1e260 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
1e270 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
1e280 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
1e290 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
1e2a0 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
1e2b0 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
1e2c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
1e2d0 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
1e2e0 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
1e2f0 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
1e300 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
1e310 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
1e320 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1e330 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
1e340 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
1e350 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
1e360 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1e370 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
1e380 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
1e390 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
1e3a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1e3b0 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
1e3c0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1e3d0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
1e3e0 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  reset..*/.SQLITE
1e3f0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
1e400 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  64 SQLITE_STDCAL
1e410 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  L sqlite3_memory
1e420 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c  _used(void);.SQL
1e430 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
1e440 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44  int64 SQLITE_STD
1e450 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d  CALL sqlite3_mem
1e460 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1e470 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1e480 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1e490 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1e4a0 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1e4b0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1e4c0 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1e4d0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1e4e0 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1e4f0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1e500 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1e510 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1e520 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1e530 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1e540 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1e550 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1e560 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1e570 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1e580 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1e590 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1e5a0 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1e5b0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1e5c0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1e5d0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1e5e0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1e5f0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1e600 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1e610 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1e620 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1e630 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1e640 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1e650 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1e660 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1e670 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74  * ^The P paramet
1e680 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c  er can be a NULL
1e690 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1e6a0 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
1e6b0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72   has not been pr
1e6c0 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20  eviously called 
1e6d0 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f  or if the previo
1e6e0 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e  us.** call had N
1e6f0 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f   less than one o
1e700 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
1e710 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65   for P, then the
1e720 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64   PRNG is.** seed
1e730 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
1e740 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ess obtained fro
1e750 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1e760 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74  s method of.** t
1e770 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1e780 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
1e790 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76  .** ^If the prev
1e7a0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
1e7b0 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e  s routine had an
1e7c0 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20   N of 1 or more 
1e7d0 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c  and a.** non-NUL
1e7e0 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65  L P then the pse
1e7f0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
1e800 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
1e810 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
1e820 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
1e830 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
1e840 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
1e850 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51  ** method..*/.SQ
1e860 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
1e870 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1e880 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
1e890 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
1e8a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e8b0 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
1e8c0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
1e8d0 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
1e8e0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1e8f0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1e900 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
1e910 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
1e920 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
1e930 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1e940 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
1e950 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
1e960 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
1e970 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e980 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1e990 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
1e9a0 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
1e9b0 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
1e9c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1e9d0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1e9e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e9f0 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
1ea00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1ea10 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1ea20 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
1ea30 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
1ea40 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
1ea50 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
1ea60 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
1ea70 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
1ea80 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
1ea90 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
1eaa0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1eab0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1eac0 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
1ead0 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
1eae0 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
1eaf0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1eb00 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
1eb10 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1eb20 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
1eb30 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
1eb40 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
1eb50 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
1eb60 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
1eb70 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
1eb80 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
1eb90 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
1eba0 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
1ebb0 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
1ebc0 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
1ebd0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
1ebe0 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
1ebf0 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
1ec00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ec10 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1ec20 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
1ec30 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
1ec40 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
1ec50 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
1ec60 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
1ec70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ec80 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1ec90 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1eca0 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
1ecb0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1ecc0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1ecd0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
1ece0 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1ecf0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1ed00 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
1ed10 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
1ed20 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
1ed30 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
1ed40 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1ed50 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
1ed60 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
1ed70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1ed80 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1ed90 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1eda0 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
1edb0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1edc0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1edd0 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
1ede0 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
1edf0 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
1ee00 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
1ee10 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1ee20 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ee30 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1ee40 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
1ee50 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
1ee60 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1ee70 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
1ee80 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1ee90 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
1eea0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1eeb0 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
1eec0 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
1eed0 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
1eee0 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
1eef0 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
1ef00 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
1ef10 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
1ef20 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
1ef30 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1ef40 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
1ef50 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1ef60 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
1ef70 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
1ef80 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
1ef90 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1efa0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
1efb0 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1efc0 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
1efd0 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
1efe0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1eff0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1f000 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1f010 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
1f020 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1f030 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
1f040 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
1f050 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1f060 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1f070 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1f080 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
1f090 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1f0a0 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
1f0b0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
1f0c0 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
1f0d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
1f0e0 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
1f0f0 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
1f100 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
1f110 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
1f120 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1f130 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1f140 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
1f150 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1f160 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
1f170 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
1f180 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
1f190 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
1f1a0 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
1f1b0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
1f1c0 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
1f1d0 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
1f1e0 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
1f1f0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
1f200 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
1f210 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1f220 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
1f230 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1f240 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
1f250 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
1f260 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
1f270 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1f280 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
1f290 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
1f2a0 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
1f2b0 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
1f2c0 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
1f2d0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
1f2e0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
1f2f0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
1f300 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
1f310 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
1f320 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
1f330 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
1f340 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
1f350 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
1f360 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
1f370 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
1f380 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
1f390 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
1f3a0 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
1f3b0 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
1f3c0 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
1f3d0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
1f3e0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
1f3f0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
1f400 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
1f410 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
1f420 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
1f430 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
1f440 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1f450 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
1f460 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
1f470 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
1f480 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
1f490 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1f4a0 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
1f4b0 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
1f4c0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
1f4d0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
1f4e0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
1f4f0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
1f500 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1f510 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
1f520 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
1f530 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
1f540 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1f550 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
1f560 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
1f570 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
1f580 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
1f590 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
1f5a0 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
1f5b0 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
1f5c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
1f5d0 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
1f5e0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1f5f0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
1f600 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
1f610 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
1f620 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
1f630 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
1f640 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
1f650 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
1f660 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
1f670 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1f680 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
1f690 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f6a0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1f6b0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1f6c0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1f6d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f6e0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1f6f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1f700 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
1f710 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1f720 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1f730 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f740 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1f750 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1f760 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1f770 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1f780 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1f790 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1f7a0 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
1f7b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
1f7c0 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
1f7d0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
1f7e0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
1f7f0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
1f800 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
1f810 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
1f820 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
1f830 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
1f840 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
1f850 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
1f860 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
1f870 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f880 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
1f890 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
1f8a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f8b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
1f8c0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
1f8d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1f8e0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
1f8f0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
1f900 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1f910 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
1f920 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
1f930 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
1f940 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
1f950 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
1f960 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
1f970 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
1f980 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
1f990 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
1f9a0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
1f9b0 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
1f9c0 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
1f9d0 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
1f9e0 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
1f9f0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
1fa00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
1fa10 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1fa20 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1fa30 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
1fa40 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
1fa50 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1fa60 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1fa70 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1fa80 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
1fa90 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
1faa0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fab0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
1fac0 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
1fad0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1fae0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1faf0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1fb00 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
1fb10 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
1fb20 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
1fb30 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
1fb40 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
1fb50 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
1fb60 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
1fb70 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
1fb80 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
1fb90 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
1fba0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1fbb0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1fbc0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
1fbd0 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
1fbe0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1fbf0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
1fc00 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
1fc10 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
1fc20 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c   [conflict resol
1fc30 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72  ution mode].** r
1fc40 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65  eturned from the
1fc50 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
1fc60 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
1fc70 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
1fc80 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
1fc90 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
1fca0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1fcb0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
1fcc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fcd0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
1fce0 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
1fcf0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
1fd00 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
1fd10 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1fd20 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
1fd30 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
1fd40 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1fd50 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
1fd60 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
1fd70 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
1fd80 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
1fd90 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
1fda0 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
1fdb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
1fdc0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
1fdd0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1fde0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1fdf0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
1fe00 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
1fe10 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
1fe20 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
1fe30 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
1fe40 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
1fe50 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
1fe60 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1fe70 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
1fe80 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
1fe90 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
1fea0 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
1feb0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
1fec0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
1fed0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
1fee0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
1fef0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1ff00 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
1ff10 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1ff20 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
1ff30 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
1ff40 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
1ff50 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
1ff60 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
1ff70 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1ff80 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
1ff90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1ffa0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1ffb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1ffc0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1ffd0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
1ffe0 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
1fff0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
20000 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
20010 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
20020 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
20030 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
20040 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
20050 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
20060 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
20070 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
20080 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
20090 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
200a0 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
200b0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
200c0 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
200d0 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
200e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
200f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20100 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
20110 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
20120 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
20130 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
20140 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
20150 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
20160 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
20170 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20180 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
20190 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
201a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
201b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
201c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
201d0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
201e0 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
201f0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
20200 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20210 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20220 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
20230 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
20240 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20250 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20260 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20270 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
20280 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
20290 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
202a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
202b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
202c0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
202d0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
202e0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
202f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20310 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
20320 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
20330 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
20340 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
20350 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
20360 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
20370 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
20380 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
20390 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
203a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
203b0 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
203c0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
203d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
203e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
203f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
20400 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
20410 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
20420 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
20430 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
20440 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
20450 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
20460 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
20470 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
20480 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20490 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
204a0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
204b0 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
204c0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
204d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
204e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
204f0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
20500 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
20510 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
20520 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20530 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
20540 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
20550 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
20560 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
20570 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20580 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
20590 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
205a0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
205b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
205c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
205d0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
205e0 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
205f0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
20600 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
20610 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20620 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
20630 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
20640 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
20650 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20660 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20670 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
20680 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
20690 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
206a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
206b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
206c0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
206d0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
206e0 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
206f0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
20700 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20710 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
20720 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
20730 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20740 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
20750 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20760 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
20770 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
20780 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
20790 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
207a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
207b0 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
207c0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
207d0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
207e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
207f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20800 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
20810 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
20820 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
20830 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
20840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
20850 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
20860 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
20870 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
20880 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
208a0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
208b0 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
208c0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
208d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
208e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
208f0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
20900 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
20910 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
20920 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
20930 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
20940 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
20950 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
20960 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
20970 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20980 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
20990 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
209a0 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
209b0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
209c0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
209d0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
209e0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
209f0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
20a00 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
20a10 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
20a20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
20a30 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
20a40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
20a50 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
20a60 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
20a70 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
20a80 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
20a90 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
20aa0 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
20ab0 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
20ac0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
20ad0 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
20ae0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
20af0 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
20b00 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
20b10 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
20b20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
20b30 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
20b40 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
20b50 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20  ITE_RECURSIVE   
20b60 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a           33   /*
20b70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20b80 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20b90 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
20ba0 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
20bb0 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
20bc0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
20bd0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
20be0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
20bf0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
20c00 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
20c10 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
20c20 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
20c30 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
20c40 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
20c50 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
20c60 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
20c70 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
20c80 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
20c90 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
20ca0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
20cb0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
20cc0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
20cd0 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
20ce0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
20cf0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
20d00 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
20d10 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
20d20 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
20d30 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
20d40 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
20d50 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
20d60 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
20d70 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
20d80 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
20d90 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
20da0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
20db0 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
20dc0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
20dd0 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
20de0 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
20df0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
20e00 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
20e10 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
20e20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
20e30 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
20e40 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
20e50 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
20e60 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
20e70 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
20e80 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
20e90 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
20ea0 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
20eb0 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
20ec0 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
20ed0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
20ee0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
20ef0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
20f00 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
20f10 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
20f20 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
20f30 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
20f40 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
20f50 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
20f60 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
20f70 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
20f80 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
20f90 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
20fa0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
20fb0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
20fc0 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
20fd0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
20fe0 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
20ff0 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
21000 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
21010 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
21020 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
21030 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
21040 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
21050 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
21060 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
21070 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
21080 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
21090 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
210a0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
210b0 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
210c0 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
210d0 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
210e0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
210f0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
21100 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
21110 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
21120 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
21130 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
21140 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
21150 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
21160 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
21170 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
21180 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72  DCALL sqlite3_tr
21190 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
211a0 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
211b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
211c0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
211d0 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49  PI SQLITE_EXPERI
211e0 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 53 51 4c  MENTAL void *SQL
211f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
21200 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
21210 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
21220 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
21230 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
21240 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
21250 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
21260 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
21270 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
21280 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
21290 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
212a0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
212b0 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
212c0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
212d0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
212e0 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
212f0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
21300 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
21310 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
21320 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
21330 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
21340 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
21350 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
21360 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
21370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
21380 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
21390 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
213a0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
213b0 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
213c0 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
213d0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
213e0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
213f0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
21400 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
21410 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
21420 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
21430 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
21440 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
21450 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
21460 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
21470 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
21480 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
21490 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
214a0 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
214b0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
214c0 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
214d0 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
214e0 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
214f0 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
21500 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
21510 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
21520 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
21530 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
21540 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
21550 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
21560 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
21570 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
21580 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
21590 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
215a0 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
215b0 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
215c0 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
215d0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
215e0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
215f0 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
21600 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
21610 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
21620 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
21630 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
21640 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
21650 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
21660 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
21670 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
21680 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
21690 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
216a0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
216b0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
216c0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
216d0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
216e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
216f0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
21700 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
21710 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
21720 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
21730 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21740 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
21750 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
21760 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
21770 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
21780 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
21790 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
217a0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
217b0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
217c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
217d0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
217e0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
217f0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
21800 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
21810 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
21820 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
21830 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
21840 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
21850 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
21860 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21870 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
21880 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
21890 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  on.** CONSTRUCTO
218a0 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
218b0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
218c0 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
218d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
218e0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
218f0 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  e .** filename a
21900 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
21910 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
21920 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
21930 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
21940 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
21950 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
21960 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
21970 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
21980 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
21990 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
219a0 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
219b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
219c0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
219d0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
219e0 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
219f0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
21a00 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
21a10 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
21a20 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
21a30 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
21a40 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
21a50 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
21a60 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
21a70 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
21a80 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
21a90 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
21aa0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
21ab0 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
21ac0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
21ad0 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
21ae0 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
21af0 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
21b00 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
21b10 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
21b20 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
21b30 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
21b40 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
21b50 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
21b60 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
21b70 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
21b80 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
21b90 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
21ba0 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
21bb0 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
21bc0 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
21bd0 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
21be0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
21bf0 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
21c00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
21c10 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c  ult encoding wil
21c20 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64  l be UTF-8 for d
21c30 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64  atabases created
21c40 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65   using.** sqlite
21c50 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
21c60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
21c70 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
21c80 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61  oding for databa
21c90 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75  ses.** created u
21ca0 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  sing sqlite3_ope
21cb0 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54  n16() will be UT
21cc0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
21cd0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
21ce0 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
21cf0 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
21d00 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
21d10 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
21d20 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
21d30 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
21d40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
21d50 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
21d60 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
21d70 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
21d80 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
21d90 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
21da0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
21db0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
21dc0 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
21dd0 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
21de0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
21df0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
21e00 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
21e10 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
21e20 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
21e30 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
21e40 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
21e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
21e60 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
21e70 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
21e80 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
21e90 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
21ea0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
21eb0 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
21ec0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
21ed0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
21ee0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
21ef0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
21f00 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
21f10 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
21f20 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
21f30 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
21f40 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
21f50 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
21f60 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
21f70 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
21f80 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
21f90 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
21fa0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
21fb0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
21fc0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
21fd0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
21fe0 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
21ff0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
22000 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
22010 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
22020 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
22030 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
22040 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
22050 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
22060 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
22070 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
22080 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
22090 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
220a0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
220b0 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
220c0 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
220d0 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
220e0 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
220f0 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
22100 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
22110 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
22120 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
22130 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
22140 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
22150 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
22160 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
22170 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
22180 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
22190 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
221a0 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
221b0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
221c0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
221d0 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
221e0 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
221f0 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
22200 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
22210 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
22220 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
22230 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
22240 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
22250 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
22260 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
22270 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
22280 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
22290 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
222a0 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
222b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
222c0 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
222d0 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
222e0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
222f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
22300 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
22310 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
22320 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
22330 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
22340 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
22350 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
22360 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
22370 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
22380 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
22390 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
223a0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
223b0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
223c0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
223d0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
223e0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
223f0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
22400 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
22410 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
22420 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
22430 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
22440 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
22450 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
22460 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
22470 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
22480 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
22490 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
224a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
224b0 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
224c0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
224d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
224e0 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
224f0 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
22500 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
22510 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
22520 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
22530 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
22540 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
22550 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
22560 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
22570 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
22580 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
22590 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
225a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
225b0 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
225c0 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
225d0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
225e0 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
225f0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
22600 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
22610 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
22620 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
22630 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
22640 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
22650 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
22660 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
22670 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
22680 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
22690 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
226a0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
226b0 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
226c0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
226d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
226e0 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
226f0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
22700 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
22710 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
22720 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
22730 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
22740 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
22750 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
22760 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
22770 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
22780 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
22790 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
227a0 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
227b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
227c0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
227d0 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
227e0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
227f0 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
22800 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
22810 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
22820 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
22830 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
22840 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
22850 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
22860 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
22870 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
22880 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
22890 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
228a0 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
228b0 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
228c0 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
228d0 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
228e0 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
228f0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
22900 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
22910 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
22920 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
22930 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
22940 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
22950 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
22960 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
22970 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
22980 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
22990 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
229a0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
229b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
229c0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
229d0 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
229e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
229f0 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
22a00 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
22a10 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
22a20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
22a30 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
22a40 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
22a50 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
22a60 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
22a70 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
22a80 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
22a90 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
22aa0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
22ab0 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
22ac0 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
22ad0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
22ae0 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
22af0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
22b00 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
22b10 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
22b20 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
22b30 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
22b40 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
22b50 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
22b60 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
22b70 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
22b80 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
22b90 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
22ba0 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
22bb0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
22bc0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
22bd0 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
22be0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
22bf0 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
22c00 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
22c10 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
22c20 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
22c30 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
22c40 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
22c50 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
22c60 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
22c70 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
22c80 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
22c90 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
22ca0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
22cb0 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
22cc0 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
22cd0 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
22ce0 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
22cf0 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
22d00 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
22d10 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
22d20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
22d30 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
22d40 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
22d50 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
22d60 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
22d70 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
22d80 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
22d90 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
22da0 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
22db0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
22dc0 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
22dd0 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
22de0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
22df0 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
22e00 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
22e10 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
22e20 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
22e30 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
22e40 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
22e50 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
22e60 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
22e70 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
22e80 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
22e90 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
22ea0 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
22eb0 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
22ec0 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
22ed0 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
22ee0 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
22ef0 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
22f00 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
22f10 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
22f20 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
22f30 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
22f40 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f  . .** ^(On windo
22f50 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
22f60 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
22f70 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
22f80 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
22f90 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
22fa0 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  C:").)^.**.** [[
22fb0 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
22fc0 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
22fd0 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
22fe0 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
22ff0 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
23000 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
23010 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
23020 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
23030 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
23040 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
23050 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
23060 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73  * SQLite and its
23070 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73   built-in [VFSes
23080 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a  ] interpret the.
23090 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65  ** following que
230a0 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
230b0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
230c0 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
230d0 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
230e0 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
230f0 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
23100 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
23110 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
23120 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
23130 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
23140 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
23150 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
23160 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
23170 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
23180 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
23190 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
231a0 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
231b0 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
231c0 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
231d0 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
231e0 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
231f0 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
23200 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
23210 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
23220 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
23230 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
23240 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
23250 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
23260 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
23270 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
23280 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
23290 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
232a0 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
232b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
232c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
232d0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
232e0 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
232f0 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
23300 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
23310 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a  r "ro", "rw",.**
23320 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22       "rwc", or "
23330 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74  memory". Attempt
23340 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
23350 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
23360 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72   is.**     an er
23370 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e  ror)^. .**     ^
23380 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69  If "ro" is speci
23390 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64  fied, then the d
233a0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
233b0 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  d for read-only 
233c0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
233d0 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b  just as if the [
233e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
233f0 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62  ONLY] flag had b
23400 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a  een set in the .
23410 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67  **     third arg
23420 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
23430 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20  _open_v2(). ^If 
23440 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
23450 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
23460 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
23470 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
23480 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
23490 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
234a0 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
234b0 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
234c0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
234d0 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
234e0 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
234f0 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
23500 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
23510 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
23520 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
23530 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
23540 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
23550 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
23560 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64  TE.  ^If the mod
23570 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  e option is.**  
23580 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72     set to "memor
23590 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b  y" then a pure [
235a0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
235b0 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72  se] that never r
235c0 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77  eads.**     or w
235d0 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20  rites from disk 
235e0 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20  is used. ^It is 
235f0 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
23600 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a  ify a value for.
23610 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20  **     the mode 
23620 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
23630 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69  s less restricti
23640 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65  ve than that spe
23650 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
23660 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
23670 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  d in the third p
23680 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
23690 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
236a0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63  *.**   <li> <b>c
236b0 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63  ache</b>: ^The c
236c0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d  ache parameter m
236d0 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
236e0 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a  her "shared" or.
236f0 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22  **     "private"
23700 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f  . ^Setting it to
23710 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75   "shared" is equ
23720 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
23730 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51  ng the.**     SQ
23740 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
23750 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65  CACHE bit in the
23760 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
23770 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  passed to.**    
23780 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23790 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65  (). ^Setting the
237a0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
237b0 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73   to "private" is
237c0 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c   .**     equival
237d0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
237e0 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  he SQLITE_OPEN_P
237f0 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e  RIVATECACHE bit.
23800 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69  .**     ^If sqli
23810 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
23820 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63   used and the "c
23830 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20  ache" parameter 
23840 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a  is present in.**
23850 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e       a URI filen
23860 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f  ame, its value o
23870 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68  verrides any beh
23880 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20  avior requested 
23890 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
238a0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
238b0 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
238c0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
238d0 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a  CACHE flag..**.*
238e0 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c  *  <li> <b>psow<
238f0 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70  /b>: ^The psow p
23900 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74  arameter indicat
23910 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  es whether or no
23920 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f  t the.**     [po
23930 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74  wersafe overwrit
23940 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73  e] property does
23950 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70   or does not app
23960 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ly to the.**    
23970 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f   storage media o
23980 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61  n which the data
23990 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65  base file reside
239a0 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  s..**.**  <li> <
239b0 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54  b>nolock</b>: ^T
239c0 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65  he nolock parame
239d0 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
239e0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
239f0 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66  .**     which if
23a00 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69   set disables fi
23a10 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f  le locking in ro
23a20 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d  llback journal m
23a30 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20  odes.  This.**  
23a40 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72     is useful for
23a50 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74   accessing a dat
23a60 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73  abase on a files
23a70 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20  ystem that does 
23a80 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f  not.**     suppo
23a90 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75  rt locking.  Cau
23aa0 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20  tion:  Database 
23ab0 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74  corruption might
23ac0 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a   result if two.*
23ad0 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72  *     or more pr
23ae0 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f  ocesses write to
23af0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
23b00 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f  se and any one o
23b10 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70  f those.**     p
23b20 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f  rocesses uses no
23b30 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c  lock=1..**.**  <
23b40 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65  li> <b>immutable
23b50 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74  </b>: ^The immut
23b60 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69  able parameter i
23b70 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
23b80 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74  y.**     paramet
23b90 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  er that indicate
23ba0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
23bb0 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72  ase file is stor
23bc0 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61  ed on.**     rea
23bd0 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e  d-only media.  ^
23be0 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69  When immutable i
23bf0 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73  s set, SQLite as
23c00 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
23c10 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66  *     database f
23c20 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  ile cannot be ch
23c30 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61  anged, even by a
23c40 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69   process with hi
23c50 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76  gher.**     priv
23c60 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68  ilege, and so th
23c70 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
23c80 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61  ened read-only a
23c90 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a  nd all locking.*
23ca0 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65  *     and change
23cb0 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69   detection is di
23cc0 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e  sabled.  Caution
23cd0 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d  : Setting the im
23ce0 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70  mutable.**     p
23cf0 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74  roperty on a dat
23d00 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20  abase file that 
23d10 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61  does in fact cha
23d20 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a  nge can result.*
23d30 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65  *     in incorre
23d40 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  ct query results
23d50 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
23d60 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e  CORRUPT] errors.
23d70 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f  .**     See also
23d80 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  : [SQLITE_IOCAP_
23d90 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20  IMMUTABLE]..**  
23da0 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a       .** </ul>.*
23db0 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67  *.** ^Specifying
23dc0 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61   an unknown para
23dd0 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65  meter in the que
23de0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
23df0 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a  a URI is not an.
23e00 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72  ** error.  Futur
23e10 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
23e20 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72  Lite might under
23e30 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c  stand additional
23e40 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
23e50 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65  ters.  See "[que
23e60 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69  ry parameters wi
23e70 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69  th special meani
23e80 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66  ng to SQLite]" f
23e90 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
23ea0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
23eb0 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
23ec0 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68  me examples]] <h
23ed0 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  3>URI filename e
23ee0 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  xamples</h3>.**.
23ef0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
23f00 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65  ="1" align=cente
23f10 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  r cellpadding=5>
23f20 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49  .** <tr><th> URI
23f30 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20   filenames <th> 
23f40 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c  Results.** <tr><
23f50 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
23f60 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
23f70 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65     Open the file
23f80 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
23f90 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
23fa0 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ory..** <tr><td>
23fb0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
23fc0 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20  /data.db<br>.** 
23fd0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
23fe0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23ff0 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20  db <br> .**     
24000 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61       file://loca
24010 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f  lhost/home/fred/
24020 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64  data.db <br> <td
24030 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
24040 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
24050 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
24060 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c  d/data.db"..** <
24070 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64  tr><td> file://d
24080 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65  arkstar/home/fre
24090 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  d/data.db <td> .
240a0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
240b0 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22  rror. "darkstar"
240c0 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e   is not a recogn
240d0 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a  ized authority..
240e0 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65  ** <tr><td style
240f0 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f  ="white-space:no
24100 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20  wrap"> .**      
24110 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44      file:///C:/D
24120 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32  ocuments%20and%2
24130 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44  0Settings/fred/D
24140 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a  esktop/data.db.*
24150 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f  *     <td> Windo
24160 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68  ws only: Open th
24170 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
24180 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74   on fred's deskt
24190 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20  op on drive.**  
241a0 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65          C:. Note
241b0 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73   that the %20 es
241c0 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65  caping in this e
241d0 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74  xample is not st
241e0 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20  rictly .**      
241f0 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20      necessary - 
24200 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73  space characters
24210 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74   can be used lit
24220 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20  erally.**       
24230 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61     in URI filena
24240 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  mes..** <tr><td>
24250 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
24260 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76  de=ro&cache=priv
24270 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  ate <td> .**    
24280 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
24290 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
242a0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
242b0 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ry for read-only
242c0 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20   access..**     
242d0 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20       Regardless 
242e0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
242f0 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  t shared-cache m
24300 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
24310 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  y.**          de
24320 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69  fault, use a pri
24330 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c  vate cache..** <
24340 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
24350 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f  me/fred/data.db?
24360 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65  vfs=unix-dotfile
24370 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20   <td>.**        
24380 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f    Open file "/ho
24390 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
243a0 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61  . Use the specia
243b0 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66  l VFS "unix-dotf
243c0 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20  ile".**         
243d0 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66   that uses dot-f
243e0 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66  iles in place of
243f0 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20   posix advisory 
24400 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e  locking..** <tr>
24410 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
24420 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
24430 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
24440 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
24450 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
24460 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
24470 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
24480 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
24490 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
244a0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
244b0 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
244c0 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
244d0 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
244e0 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
244f0 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
24500 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
24510 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
24520 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
24530 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
24540 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
24550 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
24560 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
24570 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
24580 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
24590 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
245a0 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
245b0 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
245c0 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
245d0 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
245e0 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
245f0 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
24600 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
24610 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
24620 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
24630 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
24640 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
24650 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
24660 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
24670 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
24680 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
24690 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
246a0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
246b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
246c0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
246d0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
246e0 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
246f0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
24700 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
24710 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
24720 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
24730 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
24740 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
24750 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
24760 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
24770 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
24780 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
24790 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
247a0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
247b0 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
247c0 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
247d0 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
247e0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
247f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
24800 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
24810 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
24820 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
24830 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
24840 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
24850 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
24860 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ng sqlite3_open(
24870 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
24880 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69  n_v2().  Otherwi
24890 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
248a0 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
248b0 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
248c0 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
248d0 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  may fail..**.** 
248e0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
248f0 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
24900 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  y].*/.SQLITE_API
24910 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
24920 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ALL sqlite3_open
24930 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
24940 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
24950 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
24960 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
24970 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
24980 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
24990 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
249a0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
249b0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
249c0 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  LL sqlite3_open1
249d0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
249e0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
249f0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
24a00 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
24a10 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
24a20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
24a30 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
24a40 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
24a50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
24a60 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65  CALL sqlite3_ope
24a70 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
24a80 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
24a90 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
24aa0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
24ab0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
24ac0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
24ad0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
24ae0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
24af0 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
24b00 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
24b10 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
24b20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
24b30 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
24b40 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
24b50 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
24b60 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
24b70 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
24b80 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
24b90 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
24ba0 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
24bb0 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
24bc0 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
24bd0 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
24be0 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
24bf0 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
24c00 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
24c10 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
24c20 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
24c30 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
24c40 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24c50 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
24c60 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
24c70 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
24c80 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
24c90 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
24ca0 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
24cb0 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
24cc0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
24cd0 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
24ce0 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
24cf0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
24d00 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
24d10 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
24d20 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
24d30 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
24d40 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
24d50 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
24d60 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
24d70 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
24d80 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
24d90 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
24da0 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
24db0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
24dc0 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
24dd0 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
24de0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24df0 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
24e00 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
24e10 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
24e20 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
24e30 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
24e40 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
24e50 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
24e60 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
24e70 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
24e80 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
24e90 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
24ea0 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
24eb0 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
24ec0 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
24ed0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
24ee0 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
24ef0 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
24f00 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
24f10 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
24f20 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24f30 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
24f40 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
24f50 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
24f60 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
24f70 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
24f80 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
24f90 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
24fa0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
24fb0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
24fc0 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
24fd0 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
24fe0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
24ff0 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
25000 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
25010 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
25020 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
25030 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
25040 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
25050 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
25060 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
25070 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
25080 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
25090 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
250a0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
250b0 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
250c0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
250d0 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
250e0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
250f0 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
25100 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
25110 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
25120 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
25130 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
25140 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
25150 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
25160 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
25170 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
25180 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
25190 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
251a0 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
251b0 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
251c0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
251d0 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
251e0 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
251f0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
25200 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
25210 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
25220 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
25230 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
25240 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
25250 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
25260 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
25270 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
25280 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
25290 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
252a0 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
252b0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
252c0 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
252d0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
252e0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
252f0 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
25300 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
25310 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
25320 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
25330 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
25340 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
25350 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
25360 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  st char *SQLITE_
25370 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
25380 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
25390 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
253a0 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
253b0 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45  *zParam);.SQLITE
253c0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
253d0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
253e0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
253f0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
25400 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
25410 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
25420 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
25430 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54  ite3_int64 SQLIT
25440 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
25450 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73  3_uri_int64(cons
25460 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63  t char*, const c
25470 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  har*, sqlite3_in
25480 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t64);.../*.** CA
25490 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
254a0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
254b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
254c0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te3.**.** ^If th
254d0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71  e most recent sq
254e0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
254f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
25500 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63   .** [database c
25510 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69  onnection] D fai
25520 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71  led, then the sq
25530 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29  lite3_errcode(D)
25540 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
25550 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
25560 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
25570 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  or [extended res
25580 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
25590 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a  at.** API call..
255a0 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  ** If the most r
255b0 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77  ecent API call w
255c0 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a  as successful,.*
255d0 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
255e0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
255f0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
25600 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
25610 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
25620 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
25630 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
25640 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
25650 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
25660 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
25670 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
25680 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
25690 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
256a0 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
256b0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
256c0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
256d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
256e0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
256f0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
25700 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
25710 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
25720 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
25730 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
25740 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
25750 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
25760 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
25770 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
25780 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
25790 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
257a0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
257b0 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
257c0 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
257d0 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
257e0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
257f0 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
25800 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
25810 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
25820 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
25830 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
25840 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
25850 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
25860 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
25870 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25880 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
25890 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
258a0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
258b0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
258c0 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
258d0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
258e0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
258f0 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
25900 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
25910 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
25920 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
25930 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
25940 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
25950 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
25960 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
25970 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
25980 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
25990 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
259a0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
259b0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
259c0 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
259d0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
259e0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
259f0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
25a00 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
25a10 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
25a20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
25a30 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
25a40 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
25a50 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
25a60 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
25a70 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
25a80 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
25a90 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
25aa0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
25ab0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
25ac0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25ad0 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
25ae0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
25af0 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
25b00 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
25b10 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
25b20 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
25b30 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
25b40 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
25b50 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
25b60 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
25b70 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
25b80 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
25b90 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
25ba0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
25bb0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
25bc0 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
25bd0 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
25be0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
25bf0 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
25c00 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
25c10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
25c20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
25c30 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
25c40 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
25c50 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
25c60 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
25c70 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
25c80 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72  CALL sqlite3_err
25c90 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
25ca0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
25cb0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
25cc0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
25cd0 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
25ce0 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41  3 *db);.SQLITE_A
25cf0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
25d00 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
25d10 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
25d20 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
25d30 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
25d40 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
25d50 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
25d60 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45  qlite3*);.SQLITE
25d70 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
25d80 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
25d90 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69  sqlite3_errstr(i
25da0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
25db0 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53  3REF: Prepared S
25dc0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
25dd0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
25de0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25df0 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
25e00 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
25e10 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
25e20 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
25e30 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
25e40 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a   statement that.
25e50 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70  ** has been comp
25e60 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79  iled into binary
25e70 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61   form and is rea
25e80 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  dy to be evaluat
25e90 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20  ed..**.** Think 
25ea0 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  of each SQL stat
25eb0 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72  ement as a separ
25ec0 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f  ate computer pro
25ed0 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72  gram.  The.** or
25ee0 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20  iginal SQL text 
25ef0 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20  is source code. 
25f00 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74   A prepared stat
25f10 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a  ement object .**
25f20 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64   is the compiled
25f30 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41   object code.  A
25f40 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63  ll SQL must be c
25f50 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a  onverted into a.
25f60 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
25f70 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20  ement before it 
25f80 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a  can be run..**.*
25f90 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65  * The life-cycle
25fa0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73   of a prepared s
25fb0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
25fc0 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b  usually goes lik
25fd0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
25fe0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
25ff0 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  e the prepared s
26000 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
26010 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
26020 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a  repare_v2()]..**
26030 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
26040 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73  s to [parameters
26050 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
26060 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
26070 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
26080 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
26090 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
260a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
260b0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
260c0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
260d0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
260e0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
260f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
26100 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
26110 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
26120 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
26130 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
26140 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
26150 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
26160 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
26170 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  ()]..** </ol>.*/
26180 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
26190 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
261a0 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
261b0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
261c0 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d  time Limits.** M
261d0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
261e0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
261f0 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
26200 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
26210 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
26220 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
26230 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
26240 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
26250 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
26260 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
26270 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
26280 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
26290 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
262a0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
262b0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
262c0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
262d0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
262e0 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
262f0 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
26300 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
26310 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
26320 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
26330 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
26340 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
26350 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
26360 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
26370 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
26380 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
26390 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
263a0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
263b0 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
263c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
263d0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
263e0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
263f0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
26400 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
26410 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
26420 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
26430 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
26440 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
26450 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
26460 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
26470 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
26480 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
26490 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
264a0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
264b0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
264c0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
264d0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
264e0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
264f0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
26500 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
26510 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
26520 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
26530 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
26540 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
26550 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
26560 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26570 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
26580 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
26590 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
265a0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
265b0 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
265c0 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
265d0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
265e0 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
265f0 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
26600 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
26610 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
26620 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
26630 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
26640 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
26650 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
26660 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
26670 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
26680 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
26690 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
266a0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
266b0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
266c0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
266d0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
266e0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
266f0 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
26700 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
26710 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
26720 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
26730 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
26740 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
26750 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
26760 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
26770 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
26780 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
26790 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
267a0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
267b0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
267c0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
267d0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
267e0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
267f0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
26800 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
26810 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
26820 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
26830 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
26840 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
26850 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
26860 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
26870 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
26880 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
26890 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
268a0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
268b0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
268c0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
268d0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
268e0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
268f0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
26900 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
26910 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
26920 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
26930 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
26940 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
26950 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
26960 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
26970 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49  eleases..*/.SQLI
26980 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
26990 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
269a0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
269b0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
269c0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
269d0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
269e0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
269f0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
26a00 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
26a10 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
26a20 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
26a30 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
26a40 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
26a50 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
26a60 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
26a70 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
26a80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
26a90 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
26aa0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
26ab0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
26ac0 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
26ad0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
26ae0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
26af0 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
26b00 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
26b10 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
26b20 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
26b30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26b40 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
26b50 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
26b60 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
26b70 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
26b80 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
26b90 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
26ba0 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
26bb0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26bc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
26bd0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
26be0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
26bf0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
26c00 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
26c10 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
26c20 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
26c30 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
26c40 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26c50 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
26c60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
26c70 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
26c80 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
26c90 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
26ca0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
26cb0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
26cc0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
26cd0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
26ce0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
26cf0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
26d00 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
26d10 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
26d20 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
26d30 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26d40 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
26d50 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
26d60 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
26d70 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
26d80 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
26d90 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
26da0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
26db0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
26dc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26dd0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
26de0 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
26df0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
26e00 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
26e10 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26e20 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
26e30 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
26e40 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
26e50 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
26e60 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
26e70 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
26e80 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
26e90 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
26ea0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
26eb0 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
26ec0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
26ed0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
26ee0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
26ef0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
26f00 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
26f10 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
26f20 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
26f30 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
26f40 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
26f50 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
26f60 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
26f70 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
26f80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
26f90 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
26fa0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
26fb0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
26fc0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26fd0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
26fe0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
26ff0 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
27000 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
27010 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
27020 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
27030 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
27040 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
27050 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
27060 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
27070 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
27080 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27090 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
270a0 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
270b0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
270c0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
270d0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
270e0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
270f0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
27100 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
27110 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
27120 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
27130 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
27140 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
27150 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
27160 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
27170 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
27180 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
27190 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
271a0 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
271b0 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
271c0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
271d0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
271e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
271f0 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
27200 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
27210 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
27220 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
27230 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
27240 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
27250 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ers.</dd>)^.**.*
27260 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
27270 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d  _WORKER_THREADS]
27280 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27290 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
272a0 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ADS</dt>.** <dd>
272b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
272c0 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20  er of auxiliary 
272d0 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74  worker threads t
272e0 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20  hat a single.** 
272f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27300 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c  ent] may start.<
27310 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
27320 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
27330 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
27340 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27350 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
27360 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
27370 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
27380 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
27390 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
273a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
273b0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
273c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
273d0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
273e0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
273f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
27400 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
27410 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
27420 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
27430 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
27440 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
27450 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
27460 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
27470 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
27480 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
27490 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
274a0 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
274b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
274c0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
274d0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
274e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
274f0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
27500 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
27510 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27520 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
27530 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
27540 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27550 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
27560 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a  S           11..
27570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27580 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
27590 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
275a0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
275b0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
275c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
275d0 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  te3.** CONSTRUCT
275e0 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
275f0 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
27600 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
27610 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
27620 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
27630 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
27640 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
27650 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
27660 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
27670 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
27680 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
27690 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
276a0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
276b0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
276c0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
276d0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
276e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
276f0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
27700 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
27710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27720 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
27730 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
27740 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
27750 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
27760 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
27770 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
27780 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
27790 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
277a0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
277b0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
277c0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
277d0 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
277e0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
277f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
27800 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
27810 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
27820 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
27830 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
27840 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
27850 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
27860 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
27870 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
27880 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
27890 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
278a0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69  positive, then i
278b0 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  t is the.** numb
278c0 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64  er of bytes read
278d0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66   from zSql.  ^If
278e0 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20   nByte is zero, 
278f0 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64  then no prepared
27900 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73  .** statement is
27910 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49   generated..** I
27920 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
27930 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ws that the supp
27940 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
27950 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
27960 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20  hen.** there is 
27970 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61  a small performa
27980 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
27990 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
279a0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
279b0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
279c0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
279d0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
279e0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
279f0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
27a00 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nator..**.** ^If
27a10 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
27a20 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
27a30 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
27a40 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
27a50 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
27a60 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
27a70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
27a80 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
27a90 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
27aa0 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
27ab0 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
27ac0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
27ad0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
27ae0 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
27af0 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
27b00 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
27b10 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
27b20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
27b30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27b40 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
27b50 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
27b60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27b70 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
27b80 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
27b90 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
27ba0 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
27bb0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
27bc0 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
27bd0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
27be0 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
27bf0 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
27c00 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
27c10 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
27c20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
27c30 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
27c40 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
27c50 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
27c60 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
27c70 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
27c80 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
27c90 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
27ca0 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
27cb0 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
27cc0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
27cd0 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
27ce0 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
27cf0 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
27d00 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
27d10 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
27d20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
27d30 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
27d40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
27d50 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
27d60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
27d70 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
27d80 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
27d90 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
27da0 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
27db0 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
27dc0 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
27dd0 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
27de0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
27df0 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
27e00 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
27e10 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
27e20 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
27e30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
27e40 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
27e50 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
27e60 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
27e70 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
27e80 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
27e90 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
27ea0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
27eb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
27ec0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
27ed0 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
27ee0 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
27ef0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
27f00 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
27f10 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
27f20 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
27f30 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
27f40 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
27f50 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
27f60 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
27f70 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
27f80 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
27f90 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
27fa0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
27fb0 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
27fc0 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
27fd0 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
27fe0 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
27ff0 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
28000 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
28010 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
28020 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
28030 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
28040 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
28050 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
28060 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
28070 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
28080 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
28090 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
280a0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
280b0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
280c0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
280d0 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
280e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
280f0 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
28100 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
28110 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
28120 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
28130 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
28140 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
28150 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
28160 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
28170 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
28180 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
28190 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
281a0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
281b0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
281c0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
281d0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
281e0 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
281f0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
28200 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
28210 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
28220 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
28230 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
28240 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
28250 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
28260 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
28270 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
28280 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
28290 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
282a0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
282b0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
282c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
282d0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
282e0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
282f0 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
28300 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
28310 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
28320 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
28330 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
28340 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
28350 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
28360 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
28370 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
28380 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
28390 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
283a0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
283b0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
283c0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
283d0 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
283e0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
283f0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
28400 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
28410 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
28420 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
28430 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
28440 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
28450 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
28460 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
28470 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
28480 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
28490 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
284a0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
284b0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
284c0 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  >.*/.SQLITE_API 
284d0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
284e0 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  LL sqlite3_prepa
284f0 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
28500 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
28510 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
28520 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
28530 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
28540 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
28550 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
28560 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
28570 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
28580 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
28590 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
285a0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
285b0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
285c0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
285d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
285e0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
285f0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
28600 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
28610 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
28620 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
28630 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
28640 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28650 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
28660 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
28670 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
28680 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
28690 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
286a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
286b0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
286c0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
286d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
286e0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
286f0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
28700 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
28710 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
28720 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
28730 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
28740 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
28750 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
28760 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
28770 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
28780 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
28790 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
287a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
287b0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
287c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
287d0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
287e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
287f0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
28800 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
28810 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
28820 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
28830 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
28840 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
28850 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
28860 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
28870 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
28880 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
28890 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
288a0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
288b0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
288c0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
288d0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
288e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
288f0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
28900 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28910 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
28920 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
28930 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
28940 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
28950 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
28960 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
28970 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
28980 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
28990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
289a0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
289b0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
289c0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
289d0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
289e0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
289f0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
28a00 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
28a10 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
28a20 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
28a30 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
28a40 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
28a50 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
28a60 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
28a70 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
28a80 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
28a90 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
28aa0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
28ab0 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
28ac0 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
28ad0 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
28ae0 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
28af0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28b00 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
28b10 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
28b20 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
28b30 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
28b40 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
28b50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
28b60 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  v2()]..*/.SQLITE
28b70 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
28b80 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
28b90 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
28ba0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
28bb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28bc0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
28bd0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
28be0 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
28bf0 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  base.** METHOD: 
28c00 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
28c10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28c20 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
28c30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
28c40 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
28c50 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
28c60 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
28c70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
28c80 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
28c90 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
28ca0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
28cb0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
28cc0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
28cd0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
28ce0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
28cf0 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
28d00 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
28d10 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
28d20 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
28d30 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
28d40 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
28d50 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
28d60 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
28d70 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
28d80 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
28d90 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
28da0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
28db0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
28dc0 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
28dd0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
28de0 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
28df0 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
28e00 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
28e10 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
28e20 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
28e30 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
28e40 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
28e50 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
28e60 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
28e70 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
28e80 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
28e90 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
28ea0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
28eb0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
28ec0 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
28ed0 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
28ee0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
28ef0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
28f00 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
28f10 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
28f20 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
28f30 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
28f40 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
28f50 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
28f60 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
28f70 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
28f80 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
28f90 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
28fa0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
28fb0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
28fc0 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
28fd0 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
28fe0 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
28ff0 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
29000 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
29010 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
29020 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
29030 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
29040 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
29050 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
29060 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
29070 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
29080 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
29090 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
290a0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
290b0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
290c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
290d0 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
290e0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
290f0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
29100 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
29110 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  n disk..*/.SQLIT
29120 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
29130 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
29140 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73  _stmt_readonly(s
29150 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
29160 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
29170 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
29180 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  If A Prepared St
29190 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e  atement Has Been
291a0 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44   Reset.** METHOD
291b0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
291c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
291d0 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
291e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
291f0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
29200 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
29210 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29220 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
29230 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
29240 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
29250 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
29260 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20   has not run to 
29270 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f  completion and/o
29280 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65  r has not .** be
29290 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b  en reset using [
292a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
292b0 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
292c0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a  _stmt_busy(S).**
292d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
292e0 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73  ns false if S is
292f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
29300 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20    If S is not a 
29310 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
29320 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f   and is not a po
29330 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64  inter to a valid
29340 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29350 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c  ment].** object,
29360 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
29370 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  or is undefined 
29380 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
29390 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
293a0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
293b0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f  an be used in co
293c0 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74  mbination [sqlit
293d0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a  e3_next_stmt()].
293e0 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ** to locate all
293f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29400 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
29410 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
29420 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
29430 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20  hat are in need 
29440 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20  of being reset. 
29450 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65   This can be use
29460 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c  d,.** for exampl
29470 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63  e, in diagnostic
29480 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61   routines to sea
29490 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64  rch for prepared
294a0 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20   .** statements 
294b0 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67  that are holding
294c0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f   a transaction o
294d0 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
294e0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
294f0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74  DCALL sqlite3_st
29500 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f  mt_busy(sqlite3_
29510 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
29520 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
29530 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
29540 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
29550 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
29560 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
29570 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
29580 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
29590 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
295a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
295b0 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
295c0 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
295d0 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
295e0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
295f0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
29600 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
29610 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
29620 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
29630 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
29640 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
29650 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
29660 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
29670 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
29680 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
29690 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
296a0 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
296b0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
296c0 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
296d0 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
296e0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
296f0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
29700 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
29710 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
29720 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
29730 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
29740 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
29750 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
29760 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29770 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
29780 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
29790 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
297a0 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
297b0 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
297c0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
297d0 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
297e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54  qlite3_value.  T
297f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
29800 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65  alue_dup()] inte
29810 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
29820 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61  d to construct a
29830 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74   new .** protect
29840 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29850 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65   from an unprote
29860 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29870 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
29880 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
29890 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
298a0 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
298b0 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
298c0 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
298d0 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  n internal mutex
298e0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
298f0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
29900 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29910 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
29920 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
29930 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
29940 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29950 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
29960 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
29970 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
29980 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
29990 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
299a0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
299b0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
299c0 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
299d0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
299e0 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
299f0 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
29a00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
29a10 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
29a20 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
29a30 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
29a40 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
29a50 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
29a60 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
29a70 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
29a80 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
29a90 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
29aa0 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
29ab0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
29ac0 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
29ad0 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
29ae0 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
29af0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
29b00 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
29b10 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
29b20 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
29b30 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
29b40 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
29b50 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
29b60 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
29b70 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
29b80 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
29b90 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
29ba0 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
29bb0 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
29bc0 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
29bd0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
29be0 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
29bf0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
29c00 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
29c10 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
29c20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
29c30 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
29c40 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
29c50 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
29c60 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
29c70 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
29c80 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
29c90 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
29ca0 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
29cb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
29cc0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
29cd0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
29ce0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
29cf0 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
29d00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
29d10 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
29d20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
29d30 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
29d40 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29d50 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
29d60 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
29d70 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
29d80 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
29d90 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
29da0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
29db0 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
29dc0 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
29dd0 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
29de0 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
29df0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
29e00 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65  ject.  ^A pointe
29e10 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
29e20 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
29e30 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
29e40 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
29e50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29e60 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
29e70 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
29e80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
29e90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
29ea0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
29eb0 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
29ec0 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
29ed0 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
29ee0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
29ef0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
29f00 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
29f10 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
29f20 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
29f30 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
29f40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
29f50 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
29f60 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
29f70 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
29f80 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
29f90 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
29fa0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
29fb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
29fc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
29fd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
29fe0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
29ff0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2a000 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ents.** KEYWORDS
2a010 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  : {host paramete
2a020 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  r} {host paramet
2a030 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ers} {host param
2a040 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45  eter name}.** KE
2a050 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72  YWORDS: {SQL par
2a060 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72  ameter} {SQL par
2a070 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65  ameters} {parame
2a080 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20  ter binding}.** 
2a090 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2a0a0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  stmt.**.** ^(In 
2a0b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2a0c0 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20  t text input to 
2a0d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a0e0 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
2a0f0 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
2a100 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
2a110 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d  aced by a [param
2a120 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68  eter] that match
2a130 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77  es one of follow
2a140 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73  ing.** templates
2a150 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2a160 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
2a170 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
2a180 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
2a190 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
2a1a0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2a1b0 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20  n the templates 
2a1c0 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65  above, NNN repre
2a1d0 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72  sents an integer
2a1e0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
2a1f0 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20   VVV represents 
2a200 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  an alphanumeric 
2a210 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e  identifier.)^  ^
2a220 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
2a230 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
2a240 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
2a250 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
2a260 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
2a270 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
2a280 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
2a290 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2a2a0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
2a2b0 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
2a2c0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2a2d0 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
2a2e0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2a2f0 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a  tines is always.
2a300 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
2a310 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2a320 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
2a330 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
2a340 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a350 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
2a360 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  s..**.** ^The se
2a370 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2a380 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2a390 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
2a3a0 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54  to be set..** ^T
2a3b0 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
2a3c0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
2a3d0 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57   index of 1.  ^W
2a3e0 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  hen the same nam
2a3f0 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ed.** SQL parame
2a400 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65  ter is used more
2a410 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f   than once, seco
2a420 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
2a430 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73  t.** occurrences
2a440 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69   have the same i
2a450 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73  ndex as the firs
2a460 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a  t occurrence..**
2a470 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20   ^The index for 
2a480 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
2a490 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
2a4a0 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
2a4b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a4c0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
2a4d0 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
2a4e0 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66   ^The index.** f
2a4f0 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65  or "?NNN" parame
2a500 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75  ters is the valu
2a510 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68  e of NNN..** ^Th
2a520 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
2a530 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
2a540 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
2a550 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
2a560 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
2a570 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
2a580 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
2a590 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
2a5a0 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
2a5b0 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
2a5c0 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
2a5d0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
2a5e0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
2a5f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2a600 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
2a610 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a620 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  t16().** or sqli
2a630 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
2a640 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2a650 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  r then the fourt
2a660 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  h parameter.** i
2a670 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68  s ignored and th
2a680 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20  e end result is 
2a690 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69  the same as sqli
2a6a0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e  te3_bind_null().
2a6b0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
2a6c0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
2a6d0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
2a6e0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
2a6f0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
2a700 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2a710 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
2a720 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
2a730 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
2a740 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
2a750 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
2a760 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
2a770 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2a780 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
2a790 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2a7a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2a7b0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2a7c0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2a7d0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
2a7e0 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68   then the length
2a7f0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
2a800 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2a810 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
2a820 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
2a830 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20  rminator..** If 
2a840 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2a850 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2a860 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e  bind_blob() is n
2a870 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a  egative, then.**
2a880 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2a890 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
2a8a0 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  f a non-negative
2a8b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2a8c0 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  r is provided to
2a8d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a8e0 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  xt().** or sqlit
2a8f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2a900 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2a910 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a  _text64() then.*
2a920 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  * that parameter
2a930 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
2a940 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72  e offset.** wher
2a950 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
2a960 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72  ator would occur
2a970 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74   assuming the st
2a980 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a  ring were NUL.**
2a990 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
2a9a0 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
2a9b0 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74  ers occur at byt
2a9c0 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74  e offsets less t
2a9d0 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75  han .** the valu
2a9e0 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  e of the fourth 
2a9f0 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74  parameter then t
2aa00 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
2aa10 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a  ing value will.*
2aa20 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  * contain embedd
2aa30 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65  ed NULs.  The re
2aa40 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
2aa50 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74  ons involving st
2aa60 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d  rings.** with em
2aa70 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
2aa80 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2aa90 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
2aaa0 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20  ent to the BLOB 
2aab0 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69  and string bindi
2aac0 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  ng interfaces.**
2aad0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
2aae0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
2aaf0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
2ab00 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
2ab10 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
2ab20 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54  hed with it.  ^T
2ab30 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
2ab40 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69   called.** to di
2ab50 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
2ab60 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e  B or string even
2ab70 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
2ab80 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a  bind API fails..
2ab90 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
2aba0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
2abb0 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
2abc0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
2abd0 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
2abe0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
2abf0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
2ac00 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
2ac10 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
2ac20 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2ac30 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
2ac40 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
2ac50 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
2ac60 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
2ac70 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
2ac80 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
2ac90 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
2aca0 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
2acb0 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
2acc0 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
2acd0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2ace0 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
2acf0 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75   ^The sixth argu
2ad00 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2ad10 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75  bind_text64() mu
2ad20 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  st be one of.** 
2ad30 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
2ad40 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b  SQLITE_UTF16], [
2ad50 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
2ad60 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
2ad70 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69  6LE].** to speci
2ad80 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  fy the encoding 
2ad90 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74  of the text in t
2ada0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2adb0 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73  er.  If.** the s
2adc0 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
2add0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2ade0 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e  xt64() is not on
2adf0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f  e of the.** allo
2ae00 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e  wed values shown
2ae10 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68   above, or if th
2ae20 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
2ae30 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20  is different.** 
2ae40 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e  from the encodin
2ae50 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  g specified by t
2ae60 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  he sixth paramet
2ae70 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  er, then the beh
2ae80 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65  avior.** is unde
2ae90 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2aea0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
2aeb0 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
2aec0 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
2aed0 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
2aee0 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
2aef0 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65  h zeroes.  ^A ze
2af00 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
2af10 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
2af20 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
2af30 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
2af40 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
2af50 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
2af60 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
2af70 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
2af80 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
2af90 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
2afa0 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
2afb0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
2afc0 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
2afd0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
2afe0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
2aff0 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
2b000 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  nes..** ^A negat
2b010 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
2b020 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
2b030 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
2b040 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
2b050 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73  ^If any of the s
2b060 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2b070 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2b080 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
2b090 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74  pointer.** for t
2b0a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2b0b0 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20  tement] or with 
2b0c0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2b0d0 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a  ment for which.*
2b0e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2b0f0 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
2b100 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79  ed more recently
2b110 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72   than [sqlite3_r
2b120 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  eset()],.** then
2b130 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72   the call will r
2b140 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  eturn [SQLITE_MI
2b150 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73  SUSE].  If any s
2b160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a  qlite3_bind_().*
2b170 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73  * routine is pas
2b180 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20  sed a [prepared 
2b190 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2b1a0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2b1b0 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ed, the.** resul
2b1c0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  t is undefined a
2b1d0 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d  nd probably harm
2b1e0 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64  ful..**.** ^Bind
2b1f0 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
2b200 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
2b210 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
2b220 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75  utine..** ^Unbou
2b230 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
2b240 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
2b250 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
2b260 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2b270 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2b280 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
2b290 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a  success or an.**
2b2a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
2b2b0 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
2b2c0 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  rong..** ^[SQLIT
2b2d0 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20  E_TOOBIG] might 
2b2e0 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  be returned if t
2b2f0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72  he size of a str
2b300 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65  ing or BLOB.** e
2b310 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d  xceeds limits im
2b320 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  posed by [sqlite
2b330 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
2b340 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20  _LIMIT_LENGTH]) 
2b350 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  or.** [SQLITE_MA
2b360 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b  X_LENGTH]..** ^[
2b370 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
2b380 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
2b390 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
2b3a0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
2b3b0 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e  nge.  ^[SQLITE_N
2b3c0 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
2b3d0 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61  d if malloc() fa
2b3e0 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ils..**.** See a
2b3f0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2b400 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2b410 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
2b420 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b430 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
2b440 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2b450 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2b460 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2b470 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2b480 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  L sqlite3_bind_b
2b490 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2b4a0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2b4b0 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
2b4c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
2b4d0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2b4e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2b4f0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73  e3_bind_blob64(s
2b500 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b510 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2b520 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
2b530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b540 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
2b550 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
2b560 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2b570 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2b580 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
2b590 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
2b5a0 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41  ouble);.SQLITE_A
2b5b0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2b5c0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2b5d0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
2b5e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
2b5f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2b600 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2b610 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
2b620 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2b630 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
2b640 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
2b650 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2b660 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2b670 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
2b680 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  mt*, int);.SQLIT
2b690 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2b6a0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2b6b0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
2b6c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e  e3_stmt*,int,con
2b6d0 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69  st char*,int,voi
2b6e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
2b6f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2b700 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2b710 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2b720 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b730 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2b740 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
2b750 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
2b760 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2b770 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2b780 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33  d_text64(sqlite3
2b790 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2b7a0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
2b7b0 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2b7c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b7d0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2b7e0 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
2b7f0 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49   encoding);.SQLI
2b800 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2b810 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2b820 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
2b830 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2b840 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
2b850 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2b860 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2b870 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2b880 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
2b890 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2b8a0 69 6e 74 20 6e 29 3b 0a 53 51 4c 49 54 45 5f 41  int n);.SQLITE_A
2b8b0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2b8c0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2b8d0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71  nd_zeroblob64(sq
2b8e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b8f0 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2b900 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b910 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
2b920 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  L Parameters.** 
2b930 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2b940 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  stmt.**.** ^This
2b950 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2b960 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
2b970 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
2b980 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
2b990 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2b9a0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
2b9b0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
2b9c0 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
2b9d0 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
2b9e0 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
2b9f0 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
2ba00 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
2ba10 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
2ba20 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
2ba30 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2ba40 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
2ba50 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
2ba60 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
2ba70 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
2ba80 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
2ba90 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
2baa0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
2bab0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
2bac0 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
2bad0 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
2bae0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
2baf0 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
2bb00 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
2bb10 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
2bb20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
2bb30 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
2bb40 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
2bb50 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
2bb60 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
2bb70 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2bb80 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2bb90 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2bba0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2bbb0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2bbc0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2bbd0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2bbe0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2bbf0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2bc00 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2bc10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2bc20 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
2bc30 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2bc40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2bc50 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
2bc60 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meter.** METHOD:
2bc70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2bc80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bc90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2bca0 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
2bcb0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
2bcc0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
2bcd0 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
2bce0 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
2bcf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2bd00 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
2bd10 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2bd20 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
2bd30 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2bd40 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
2bd50 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
2bd60 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
2bd70 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2bd80 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2bd90 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
2bda0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2bdb0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
2bdc0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
2bdd0 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
2bde0 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
2bdf0 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
2be00 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
2be10 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
2be20 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
2be30 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
2be40 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
2be50 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
2be60 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
2be70 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
2be80 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
2be90 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
2bea0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2beb0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
2bec0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
2bed0 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
2bee0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
2bef0 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
2bf00 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
2bf10 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
2bf20 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
2bf30 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
2bf40 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
2bf50 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
2bf60 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
2bf70 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
2bf80 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
2bf90 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
2bfa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2bfb0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
2bfc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2bfd0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2bfe0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2bff0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2c000 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2c010 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2c020 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2c030 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2c040 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2c050 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
2c060 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2c070 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
2c080 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  L sqlite3_bind_p
2c090 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
2c0a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c0b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c0c0 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
2c0d0 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
2c0e0 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45  Given Name.** ME
2c0f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2c100 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
2c110 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
2c120 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
2c130 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
2c140 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
2c150 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
2c160 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
2c170 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
2c180 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
2c190 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2c1a0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2c1b0 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
2c1c0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
2c1d0 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
2c1e0 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
2c1f0 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
2c200 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
2c210 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
2c220 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
2c230 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
2c240 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
2c250 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
2c260 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
2c270 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2c280 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2c290 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2c2a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2c2b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2c2c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2c2d0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2c2e0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2c2f0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2c300 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2c310 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2c320 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2c330 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
2c340 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
2c350 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
2c360 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c370 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
2c380 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
2c390 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d  d Statement.** M
2c3a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2c3b0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  tmt.**.** ^Contr
2c3c0 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
2c3d0 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
2c3e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2c3f0 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
2c400 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
2c410 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
2c420 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
2c430 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2c440 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
2c450 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
2c460 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
2c470 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51  s to NULL..*/.SQ
2c480 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2c490 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2c4a0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2c4b0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2c4c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c4d0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
2c4e0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
2c4f0 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
2c500 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2c510 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2c520 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2c530 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2c540 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
2c550 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2c560 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
2c570 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
2c580 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
2c590 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
2c5a0 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
2c5b0 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
2c5c0 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
2c5d0 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
2c5e0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2c5f0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
2c600 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2c610 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2c620 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2c630 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2c640 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2c650 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2c660 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
2c670 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
2c680 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2c690 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
2c6a0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2c6b0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
2c6c0 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
2c6d0 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
2c6e0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
2c6f0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
2c700 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
2c710 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2c720 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
2c730 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2c740 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
2c750 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
2c760 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
2c770 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2c780 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
2c790 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2c7a0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
2c7b0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2c7c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2c7d0 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
2c7e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2c7f0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
2c800 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
2c810 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
2c820 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2c830 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
2c840 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
2c850 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
2c860 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
2c870 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2c880 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
2c890 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
2c8a0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
2c8b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2c8c0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
2c8d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2c8e0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2c8f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2c900 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2c910 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2c920 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2c930 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c940 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2c950 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2c960 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
2c970 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2c980 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
2c990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2c9a0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
2c9b0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
2c9c0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
2c9d0 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
2c9e0 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
2c9f0 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
2ca00 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
2ca10 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
2ca20 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
2ca30 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
2ca40 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
2ca50 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2ca60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2ca70 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
2ca80 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
2ca90 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
2caa0 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
2cab0 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
2cac0 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
2cad0 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
2cae0 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
2caf0 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
2cb00 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
2cb10 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
2cb20 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
2cb30 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
2cb40 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
2cb50 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ext..*/.SQLITE_A
2cb60 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
2cb70 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2cb80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2cb90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2cba0 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f   int N);.SQLITE_
2cbb0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2cbc0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2cbd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2cbe0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2cbf0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
2cc00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
2cc10 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
2cc20 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2cc30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2cc40 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2cc50 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
2cc60 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
2cc70 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
2cc80 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2cc90 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
2cca0 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
2ccb0 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
2ccc0 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
2ccd0 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
2cce0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
2ccf0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
2cd00 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
2cd10 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
2cd20 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
2cd30 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
2cd40 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
2cd50 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
2cd60 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
2cd70 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
2cd80 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
2cd90 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
2cda0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
2cdb0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
2cdc0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
2cdd0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
2cde0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
2cdf0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2ce00 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
2ce10 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
2ce20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
2ce30 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
2ce40 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2ce50 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2ce60 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2ce70 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2ce80 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2ce90 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2cea0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ceb0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2cec0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2ced0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
2cee0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
2cef0 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
2cf00 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
2cf10 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
2cf20 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
2cf30 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
2cf40 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
2cf50 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
2cf60 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2cf70 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
2cf80 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2cf90 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
2cfa0 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
2cfb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cfc0 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
2cfd0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
2cfe0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2cff0 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
2d000 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2d010 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
2d020 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
2d030 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
2d040 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
2d050 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
2d060 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
2d070 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
2d080 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
2d090 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
2d0a0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
2d0b0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
2d0c0 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
2d0d0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
2d0e0 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
2d0f0 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
2d100 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2d110 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
2d120 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
2d130 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
2d140 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
2d150 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2d160 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
2d170 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
2d180 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2d190 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
2d1a0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2d1b0 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
2d1c0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
2d1d0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
2d1e0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
2d1f0 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
2d200 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
2d210 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
2d220 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
2d230 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
2d240 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
2d250 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
2d260 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2d270 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
2d280 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
2d290 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2d2a0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2d2b0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2d2c0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2d2d0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2d2e0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2d2f0 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
2d300 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2d310 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2d320 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2d330 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
2d340 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
2d350 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d360 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
2d370 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2d380 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2d390 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
2d3a0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
2d3b0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2d3c0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2d3d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2d3e0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2d3f0 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
2d400 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
2d410 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2d420 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d430 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
2d440 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
2d450 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2d460 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2d470 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51  undefined..*/.SQ
2d480 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2d490 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
2d4a0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2d4b0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2d4c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2d4d0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2d4e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
2d4f0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2d500 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2d510 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
2d520 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2d530 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2d540 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
2d550 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2d560 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
2d570 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2d580 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2d590 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
2d5a0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2d5b0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2d5c0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2d5d0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2d5e0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
2d5f0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2d600 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2d610 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
2d620 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2d630 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2d640 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
2d650 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
2d660 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
2d670 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2d680 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2d690 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
2d6a0 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
2d6b0 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
2d6c0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2d6d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72  .**.** ^(The fir
2d6e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2d6f0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2d700 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
2d710 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
2d720 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2d730 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
2d740 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
2d750 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
2d760 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
2d770 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
2d780 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
2d790 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2d7a0 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
2d7b0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2d7c0 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
2d7d0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
2d7e0 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68  urned.)^  ^If th
2d7f0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2d800 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
2d810 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
2d820 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
2d830 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
2d840 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2d850 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2d860 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
2d870 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
2d880 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
2d890 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
2d8a0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
2d8b0 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
2d8c0 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
2d8d0 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
2d8e0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
2d8f0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
2d900 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
2d910 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
2d920 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
2d930 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
2d940 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
2d950 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
2d960 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
2d970 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
2d980 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
2d990 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
2d9a0 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
2d9b0 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a  umn (i==0).)^.**
2d9c0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
2d9d0 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
2d9e0 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a  e typing.  ^So j
2d9f0 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
2da00 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
2da10 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
2da20 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
2da30 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
2da40 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
2da50 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
2da60 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
2da70 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
2da80 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
2da90 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
2daa0 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
2dab0 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
2dac0 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20  c.  ^Type.** is 
2dad0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2dae0 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
2daf0 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
2db00 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
2db10 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
2db20 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49   values..*/.SQLI
2db30 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2db40 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
2db50 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2db60 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
2db70 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2db80 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2db90 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
2dba0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2dbb0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
2dbc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2dbd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2dbe0 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
2dbf0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
2dc00 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2dc10 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  stmt.**.** After
2dc20 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2dc30 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
2dc40 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2dc50 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2dc60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2dc70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2dc80 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2dc90 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
2dca0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
2dcb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2dcc0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2dcd0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
2dce0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
2dcf0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
2dd00 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2dd10 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
2dd20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2dd30 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
2dd40 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2dd50 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2dd60 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
2dd70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
2dd80 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
2dd90 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
2dda0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
2ddb0 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
2ddc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2ddd0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2dde0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2ddf0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
2de00 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2de10 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
2de20 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2de30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2de40 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
2de50 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
2de60 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2de70 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
2de80 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
2de90 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2dea0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
2deb0 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
2dec0 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
2ded0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2dee0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
2def0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
2df00 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
2df10 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
2df20 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
2df30 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
2df40 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
2df50 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
2df60 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2df70 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
2df80 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
2df90 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
2dfa0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2dfb0 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
2dfc0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
2dfd0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2dfe0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
2dff0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2e000 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
2e010 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
2e020 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
2e030 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
2e040 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
2e050 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2e060 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
2e070 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
2e080 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
2e090 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
2e0a0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
2e0b0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
2e0c0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2e0d0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
2e0e0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
2e0f0 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
2e100 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2e110 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
2e120 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
2e130 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
2e140 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
2e150 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
2e160 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
2e170 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2e180 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2e190 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
2e1a0 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
2e1b0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2e1c0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2e1d0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
2e1e0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
2e1f0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
2e200 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2e210 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2e220 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2e230 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
2e240 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
2e250 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
2e260 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
2e270 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
2e280 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
2e290 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
2e2a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
2e2b0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
2e2c0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
2e2d0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
2e2e0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
2e2f0 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
2e300 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
2e310 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
2e320 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2e330 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
2e340 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
2e350 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
2e360 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
2e370 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
2e380 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
2e390 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
2e3a0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
2e3b0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
2e3c0 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
2e3d0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
2e3e0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2e3f0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2e400 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
2e410 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
2e420 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
2e430 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2e440 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
2e450 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
2e460 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2e470 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
2e480 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
2e490 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
2e4a0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
2e4b0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
2e4c0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
2e4d0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
2e4e0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
2e4f0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
2e500 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e510 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
2e520 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2e530 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
2e540 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
2e550 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2e560 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
2e570 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
2e580 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2e590 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
2e5a0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
2e5b0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
2e5c0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
2e5d0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
2e5e0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
2e5f0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
2e600 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e610 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
2e620 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
2e630 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
2e640 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
2e650 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
2e660 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
2e670 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
2e680 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
2e690 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
2e6a0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
2e6b0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
2e6c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e6d0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
2e6e0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
2e6f0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
2e700 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
2e710 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
2e720 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
2e730 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
2e740 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
2e750 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
2e760 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2e770 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
2e780 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2e790 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
2e7a0 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
2e7b0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2e7c0 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
2e7d0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2e7e0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
2e7f0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
2e800 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
2e810 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2e820 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
2e830 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e840 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
2e850 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
2e860 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
2e870 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2e880 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
2e890 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
2e8a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
2e8b0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
2e8c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e8d0 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
2e8e0 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
2e8f0 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
2e900 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
2e910 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2e920 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
2e930 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
2e940 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
2e950 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
2e960 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
2e970 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
2e980 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
2e990 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
2e9a0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
2e9b0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2e9c0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
2e9d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
2e9e0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
2e9f0 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
2ea00 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
2ea10 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
2ea20 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
2ea30 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
2ea40 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
2ea50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
2ea60 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
2ea70 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
2ea80 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
2ea90 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
2eaa0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
2eab0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2eac0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
2ead0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2eae0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
2eaf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2eb00 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2eb10 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
2eb20 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
2eb30 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
2eb40 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2eb50 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
2eb60 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
2eb70 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
2eb80 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
2eb90 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
2eba0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
2ebb0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
2ebc0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2ebd0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
2ebe0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
2ebf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
2ec00 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
2ec10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ec20 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2ec30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2ec40 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
2ec50 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
2ec60 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2ec70 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2ec80 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
2ec90 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
2eca0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
2ecb0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
2ecc0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2ecd0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
2ece0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
2ecf0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
2ed00 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2ed10 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ended..*/.SQLITE
2ed20 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2ed30 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2ed40 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
2ed50 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2ed60 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
2ed70 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
2ed80 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult set.** METHO
2ed90 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2eda0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2edb0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2edc0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2edd0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2ede0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
2edf0 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
2ee00 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2ee10 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2ee20 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2ee30 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
2ee40 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
2ee50 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
2ee60 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
2ee70 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
2ee80 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2ee90 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
2eea0 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
2eeb0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
2eec0 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
2eed0 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
2eee0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
2eef0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2ef00 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
2ef10 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
2ef20 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2ef30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2ef40 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2ef50 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2ef60 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
2ef70 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
2ef80 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2ef90 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2efa0 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
2efb0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2efc0 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
2efd0 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
2efe0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
2eff0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2f000 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
2f010 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
2f020 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
2f030 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
2f040 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
2f050 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
2f060 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
2f070 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
2f080 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
2f090 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
2f0a0 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
2f0b0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
2f0c0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2f0d0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2f0e0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
2f0f0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2f100 4c 4c 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  LL sqlite3_data_
2f110 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2f120 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2f130 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2f140 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
2f150 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2f160 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
2f170 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
2f180 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2f190 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2f1a0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2f1b0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2f1c0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2f1d0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2f1e0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2f1f0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2f200 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2f210 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2f220 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2f230 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
2f240 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
2f250 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
2f260 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
2f270 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2f280 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
2f290 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
2f2a0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
2f2b0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
2f2c0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
2f2d0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
2f2e0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
2f2f0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
2f300 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
2f310 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
2f320 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
2f330 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
2f340 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
2f350 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
2f360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2f370 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
2f380 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
2f390 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2f3a0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
2f3b0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
2f3c0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
2f3d0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
2f3e0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
2f3f0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2f400 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2f410 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2f420 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2f430 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f440 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2f450 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2f460 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2f470 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2f480 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  s}.** METHOD: sq
2f490 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2f4a0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2f4b0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2f4c0 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
2f4d0 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
2f4e0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
2f4f0 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
2f500 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
2f510 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
2f520 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
2f530 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
2f540 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f550 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
2f560 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
2f570 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
2f580 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
2f590 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2f5a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2f5b0 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
2f5c0 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
2f5d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2f5e0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2f5f0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
2f600 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
2f610 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
2f620 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
2f630 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
2f640 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2f650 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
2f660 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
2f670 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2f680 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
2f690 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
2f6a0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
2f6b0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
2f6c0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
2f6d0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2f6e0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
2f6f0 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
2f700 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
2f710 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
2f720 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
2f730 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
2f740 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
2f750 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
2f760 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2f770 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
2f780 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
2f790 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2f7a0 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
2f7b0 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
2f7c0 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2f7d0 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
2f7e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2f7f0 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
2f800 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
2f810 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
2f820 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2f830 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
2f840 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2f850 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2f860 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
2f870 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
2f880 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2f890 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
2f8a0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2f8b0 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
2f8c0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2f8d0 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
2f8e0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2f8f0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2f900 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2f910 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
2f920 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
2f930 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
2f940 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
2f950 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
2f960 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
2f970 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2f980 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2f990 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
2f9a0 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
2f9b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2f9c0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2f9d0 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
2f9e0 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
2f9f0 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
2fa00 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
2fa10 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
2fa20 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
2fa30 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
2fa40 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
2fa50 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
2fa60 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
2fa70 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
2fa80 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
2fa90 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
2faa0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2fab0 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
2fac0 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
2fad0 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
2fae0 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
2faf0 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
2fb00 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
2fb10 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2fb20 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
2fb30 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2fb40 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2fb50 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
2fb60 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
2fb70 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
2fb80 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
2fb90 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
2fba0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
2fbb0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
2fbc0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
2fbd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2fbe0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2fbf0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
2fc00 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2fc10 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
2fc20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2fc30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2fc40 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2fc50 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2fc60 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2fc70 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2fc80 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2fc90 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
2fca0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2fcb0 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
2fcc0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
2fcd0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2fce0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
2fcf0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
2fd00 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
2fd10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2fd20 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
2fd30 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2fd40 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
2fd50 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
2fd60 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
2fd70 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2fd80 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2fd90 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2fda0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2fdb0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2fdc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2fdd0 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
2fde0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2fdf0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2fe00 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2fe10 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2fe20 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2fe30 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
2fe40 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2fe50 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2fe60 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
2fe70 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2fe80 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
2fe90 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2fea0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2feb0 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
2fec0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2fed0 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
2fee0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2fef0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2ff00 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2ff10 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2ff20 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2ff30 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2ff40 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2ff50 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2ff60 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2ff70 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
2ff80 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2ff90 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2ffa0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2ffb0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2ffc0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2ffd0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2ffe0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2fff0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
30000 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
30010 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
30020 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30030 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
30040 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30050 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
30060 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
30070 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
30080 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
30090 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
300a0 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
300b0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
300c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
300d0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
300e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
300f0 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
30100 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
30110 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
30120 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
30130 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
30140 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
30150 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
30160 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30170 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
30180 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
30190 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
301a0 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
301b0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
301c0 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
301d0 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
301e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
301f0 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
30200 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
30210 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
30220 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67  **.** <b>Warning
30230 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63  :</b> ^The objec
30240 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
30250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
30260 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
30270 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
30280 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30290 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74  ct.  In a multit
302a0 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d  hreaded environm
302b0 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f  ent,.** an unpro
302c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
302d0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
302e0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61 66  only be used saf
302f0 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  ely with.** [sql
30300 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
30310 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
30320 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
30330 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
30340 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30350 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
30360 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
30370 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
30380 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
30390 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
303a0 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
303b0 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
303c0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
303d0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
303e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
303f0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
30400 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
30410 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
30420 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
30430 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
30440 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
30450 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
30460 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
30470 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20  riate.  ^For.** 
30480 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
30490 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
304a0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
304b0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
304c0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
304d0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
304e0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
304f0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
30500 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
30510 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
30520 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
30530 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
30540 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
30550 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
30560 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
30570 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
30580 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
30590 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
305a0 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
305b0 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
305c0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
305d0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
305e0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
305f0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
30600 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
30610 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
30620 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
30630 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
30640 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
30650 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
30660 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
30670 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
30680 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
30690 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
306a0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
306b0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
306c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
306d0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
306e0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
306f0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
30700 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
30710 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
30720 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
30730 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
30740 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
30750 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
30760 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
30770 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
30780 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
30790 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
307a0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
307b0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
307c0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
307d0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
307e0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
307f0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
30800 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
30810 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
30820 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
30830 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
30840 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42  <td> [CAST] to B
30850 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  LOB.** <tr><td> 
30860 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
30870 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
30880 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
30890 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
308a0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
308b0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
308c0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
308d0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
308e0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
308f0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
30900 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
30910 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
30920 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
30930 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
30940 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
30950 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
30960 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
30970 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
30980 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
30990 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
309a0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
309b0 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
309c0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
309d0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  e>)^.**.** Note 
309e0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
309f0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
30a00 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
30a10 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
30a20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
30a30 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
30a40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30a50 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
30a60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30a70 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
30a80 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
30a90 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
30aa0 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
30ab0 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
30ac0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
30ad0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
30ae0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
30af0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
30b00 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
30b10 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
30b20 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
30b30 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
30b40 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
30b50 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
30b60 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
30b70 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
30b80 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
30b90 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
30ba0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
30bb0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
30bc0 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
30bd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30be0 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
30bf0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
30c00 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
30c10 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
30c20 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
30c30 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
30c40 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
30c50 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
30c60 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
30c70 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
30c80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30c90 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
30ca0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30cb0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
30cc0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
30cd0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
30ce0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
30cf0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
30d00 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
30d10 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
30d20 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
30d30 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
30d40 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
30d50 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
30d60 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
30d70 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
30d80 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
30d90 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
30da0 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
30db0 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65  ointer reference
30dc0 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  s will have been
30dd0 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
30de0 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
30df0 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
30e00 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
30e10 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
30e20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68  but sometimes th
30e30 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f  ey.** are not po
30e40 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
30e50 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
30e60 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
30e70 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  alidated..**.** 
30e80 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63  The safest polic
30e90 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
30ea0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
30eb0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
30ec0 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
30ed0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
30ee0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
30ef0 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
30f00 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
30f10 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
30f20 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
30f30 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
30f40 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
30f50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
30f60 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
30f70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30f80 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
30f90 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
30fa0 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
30fb0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
30fc0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
30fd0 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
30fe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30ff0 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
31000 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
31010 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
31020 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
31030 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
31040 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
31050 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
31060 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
31070 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31080 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
31090 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
310a0 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
310b0 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
310c0 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
310d0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
310e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
310f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
31100 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
31110 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
31120 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
31130 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
31140 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
31150 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
31160 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
31170 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
31180 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
31190 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
311a0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
311b0 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
311c0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
311d0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
311e0 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
311f0 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
31200 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
31210 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
31220 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31230 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
31240 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
31250 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
31260 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
31270 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
31280 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
31290 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61   <em>not</em> pa
312a0 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
312b0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
312c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
312d0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
312e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
312f0 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
31300 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
31310 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d  ..**.** ^(If a m
31320 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
31330 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
31340 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
31350 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
31360 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
31370 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
31380 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
31390 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
313a0 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
313b0 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
313c0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
313d0 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
313e0 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
313f0 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
31400 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
31410 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
31420 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
31430 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53  E_NOMEM].)^.*/.S
31440 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
31450 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
31460 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
31470 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
31480 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
31490 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
314a0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
314b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
314c0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
314d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
314e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
314f0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
31500 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31510 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
31520 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
31530 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65  QLITE_API double
31540 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
31550 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
31560 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
31570 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
31580 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
31590 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
315a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
315b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
315c0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
315d0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
315e0 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41  t64 SQLITE_STDCA
315f0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
31600 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
31610 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
31620 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
31630 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
31640 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
31650 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31660 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
31670 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
31680 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
31690 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
316a0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
316b0 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
316c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
316d0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
316e0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
316f0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
31700 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
31710 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
31720 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
31730 74 65 33 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54  te3_value *SQLIT
31740 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
31750 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
31760 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31770 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
31780 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
31790 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
317a0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
317b0 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c   DESTRUCTOR: sql
317c0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
317d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
317e0 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
317f0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
31800 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
31810 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
31820 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
31830 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
31840 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
31850 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65  encountered no e
31860 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74  rrors.** or if t
31870 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
31880 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75  never been evalu
31890 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ated, then sqlit
318a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65  e3_finalize() re
318b0 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f  turns.** SQLITE_
318c0 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73  OK.  ^If the mos
318d0 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
318e0 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74  ion of statement
318f0 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a   S failed, then.
31900 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ** sqlite3_final
31910 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74  ize(S) returns t
31920 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  he appropriate [
31930 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a  error code] or.*
31940 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  * [extended erro
31950 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
31960 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
31970 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20  lize(S) routine 
31980 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
31990 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
319a0 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79  g.** the life cy
319b0 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64  cle of [prepared
319c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a   statement] S:.*
319d0 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65  * before stateme
319e0 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61  nt S is ever eva
319f0 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a  luated, after.**
31a00 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c   one or more cal
31a10 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
31a20 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65  eset()], or afte
31a30 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f  r any call.** to
31a40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
31a50 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  ] regardless of 
31a60 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
31a70 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
31a80 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
31a90 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ecution..**.** ^
31aa0 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  Invoking sqlite3
31ab0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61  _finalize() on a
31ac0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
31ad0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
31ae0 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  p..**.** The app
31af0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69  lication must fi
31b00 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72  nalize every [pr
31b10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31b20 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76  ] in order to av
31b30 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20  oid.** resource 
31b40 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20  leaks.  It is a 
31b50 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66  grievous error f
31b60 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
31b70 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65  on to try to use
31b80 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73  .** a prepared s
31b90 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
31ba0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
31bb0 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f  ized.  Any use o
31bc0 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  f a prepared.** 
31bd0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
31be0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
31bf0 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74  lized can result
31c00 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
31c10 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  d.** undesirable
31c20 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61   behavior such a
31c30 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20  s segfaults and 
31c40 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e  heap corruption.
31c50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
31c60 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
31c70 4c 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  L sqlite3_finali
31c80 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
31c90 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
31ca0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
31cb0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
31cc0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d  ment Object.** M
31cd0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
31ce0 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  tmt.**.** The sq
31cf0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
31d00 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
31d10 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
31d20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31d30 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
31d40 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
31d50 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
31d60 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
31d70 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
31d80 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
31d90 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
31da0 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
31db0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
31dc0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
31dd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
31de0 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
31df0 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
31e00 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
31e10 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
31e20 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
31e30 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
31e40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
31e50 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
31e60 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
31e70 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
31e80 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
31e90 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
31ea0 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
31eb0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
31ec0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
31ed0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
31ee0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
31ef0 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
31f00 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
31f10 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
31f20 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
31f30 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
31f40 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
31f50 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
31f60 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
31f70 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
31f80 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
31f90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
31fa0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
31fb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
31fc0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
31fd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31fe0 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
31ff0 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
32000 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
32010 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
32020 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
32030 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
32040 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
32050 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
32060 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
32070 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
32080 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
32090 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
320a0 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
320b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
320c0 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ] S..*/.SQLITE_A
320d0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
320e0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65  DCALL sqlite3_re
320f0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
32100 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
32110 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
32120 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
32130 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
32140 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
32150 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
32160 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
32170 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
32180 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
32190 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
321a0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
321b0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
321c0 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
321d0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
321e0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
321f0 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
32200 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
32210 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
32220 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
32230 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
32240 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
32250 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
32260 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
32270 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
32280 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
32290 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
322a0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
322b0 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
322c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
322d0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
322e0 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
322f0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
32300 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
32310 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
32320 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
32330 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
32340 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
32350 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
32360 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
32370 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
32380 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
32390 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
323a0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
323b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
323c0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
323d0 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
323e0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
323f0 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
32400 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
32410 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
32420 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
32430 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
32440 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
32450 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
32460 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
32470 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
32480 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
32490 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
324a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
324b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
324c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
324d0 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
324e0 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
324f0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
32500 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
32510 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
32520 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
32530 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
32540 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
32550 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
32560 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
32570 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
32580 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
32590 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
325a0 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
325b0 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
325c0 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
325d0 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
325e0 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
325f0 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
32600 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
32610 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
32620 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
32630 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
32640 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
32650 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
32660 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
32670 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
32680 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
32690 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
326a0 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
326b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
326c0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
326d0 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
326e0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
326f0 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
32700 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
32710 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
32720 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
32730 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
32740 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
32750 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
32760 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
32770 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
32780 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
32790 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
327a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
327b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
327c0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
327d0 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
327e0 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
327f0 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
32800 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
32810 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
32820 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61  rameters.  The a
32830 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
32840 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d  d set this param
32850 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  eter to.** [SQLI
32860 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74  TE_UTF16LE] if t
32870 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
32880 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
32890 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  es .** [sqlite3_
328a0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
328b0 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
328c0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
328d0 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70  E] if the.** imp
328e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
328f0 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  kes [sqlite3_val
32900 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f  ue_text16be()] o
32910 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a  n an input, or.*
32920 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  * [SQLITE_UTF16]
32930 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   if [sqlite3_val
32940 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20  ue_text16()] is 
32950 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  used, or [SQLITE
32960 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77  _UTF8].** otherw
32970 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20  ise.  ^The same 
32980 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  SQL function may
32990 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
329a0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73  ultiple times us
329b0 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74  ing.** different
329c0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
329d0 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20  encodings, with 
329e0 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d  different implem
329f0 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a  entations for.**
32a00 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a   each encoding..
32a10 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
32a20 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32a30 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
32a40 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
32a50 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
32a60 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
32a70 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
32a80 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
32a90 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
32aa0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
32ab0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
32ac0 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   may optionally 
32ad0 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51  be ORed with [SQ
32ae0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
32af0 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  IC].** to signal
32b00 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69   that the functi
32b10 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  on will always r
32b20 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72  eturn the same r
32b30 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74  esult given.** t
32b40 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77  he same inputs w
32b50 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53  ithin a single S
32b60 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d  QL statement.  M
32b70 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ost SQL function
32b80 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69  s are.** determi
32b90 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69  nistic.  The bui
32ba0 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d  lt-in [random()]
32bb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
32bc0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61   an example of a
32bd0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  .** function tha
32be0 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69  t is not determi
32bf0 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c  nistic.  The SQL
32c00 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  ite query planne
32c10 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20  r is able to.** 
32c20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e  perform addition
32c30 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  al optimizations
32c40 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69   on deterministi
32c50 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20  c functions, so 
32c60 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  use.** of the [S
32c70 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
32c80 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63  TIC] flag is rec
32c90 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70  ommended where p
32ca0 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ossible..**.** ^
32cb0 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
32cc0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
32cd0 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
32ce0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
32cf0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
32d00 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
32d10 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
32d20 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
32d30 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
32d40 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
32d50 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
32d60 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
32d70 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
32d80 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
32d90 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
32da0 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
32db0 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
32dc0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
32dd0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
32de0 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
32df0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
32e00 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
32e10 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
32e20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
32e30 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
32e40 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
32e50 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
32e60 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
32e70 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
32e80 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
32e90 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
32ea0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
32eb0 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
32ec0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
32ed0 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
32ee0 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
32ef0 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
32f00 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
32f10 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
32f20 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
32f30 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20  LL pointers for 
32f40 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
32f50 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
32f60 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
32f70 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  ninth parameter 
32f80 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
32f90 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
32fa0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
32fb0 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
32fc0 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
32fd0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
32fe0 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
32ff0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
33000 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
33010 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
33020 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
33030 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
33040 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
33050 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33060 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
33070 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
33080 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
33090 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
330a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
330b0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
330c0 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
330d0 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
330e0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
330f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
33100 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
33110 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
33120 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
33130 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
33140 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
33150 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
33160 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
33170 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
33180 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33190 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
331a0 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
331b0 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
331c0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
331d0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
331e0 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
331f0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
33200 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
33210 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
33220 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
33230 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
33240 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
33250 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
33260 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
33270 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
33280 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
33290 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
332a0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
332b0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
332c0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
332d0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
332e0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
332f0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
33300 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
33310 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
33320 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
33330 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
33340 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
33350 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
33360 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
33370 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
33380 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
33390 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
333a0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
333b0 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
333c0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
333d0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
333e0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
333f0 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
33400 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
33410 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
33420 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
33430 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
33440 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
33450 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
33460 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
33470 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
33480 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
33490 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
334a0 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
334b0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
334c0 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
334d0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
334e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
334f0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
33500 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
33510 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
33520 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
33530 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
33540 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
33550 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
33560 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
33570 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
33580 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
33590 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
335a0 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
335b0 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
335c0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
335d0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
335e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
335f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
33600 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33610 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
33620 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
33630 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
33640 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
33650 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
33660 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
33670 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
33680 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
33690 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
336a0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
336b0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
336c0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
336d0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
336e0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
336f0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53  3_context*).);.S
33700 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
33710 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
33720 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33730 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
33740 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
33750 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
33760 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
33770 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
33780 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
33790 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
337a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
337b0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
337c0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
337d0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
337e0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
337f0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
33800 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
33810 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
33820 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
33830 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
33840 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33850 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
33860 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
33870 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
33880 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
33890 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
338a0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
338b0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
338c0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
338d0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
338e0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
338f0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
33900 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
33910 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
33920 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
33930 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33940 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
33950 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
33960 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33970 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
33980 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
33990 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
339a0 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
339b0 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
339c0 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
339d0 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
339e0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
339f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
33a00 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20  F8           1  
33a10 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31    /* IMP: R-3751
33a20 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69  4-35566 */.#defi
33a30 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
33a40 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a  E        2    /*
33a50 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37   IMP: R-03371-37
33a60 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  637 */.#define S
33a70 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
33a80 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50       3    /* IMP
33a90 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20  : R-51971-34154 
33aa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
33ab0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
33ac0 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
33ad0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
33ae0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
33af0 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
33b00 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74  5    /* Deprecat
33b10 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
33b20 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
33b30 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
33b40 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33b50 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
33b60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
33b70 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a  nction Flags.**.
33b80 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
33b90 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74  ts may be ORed t
33ba0 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65  ogether with the
33bb0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
33bc0 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65  8 | preferred te
33bd0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20  xt encoding] as 
33be0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
33bf0 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ent.** to [sqlit
33c00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33c10 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
33c20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
33c30 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
33c40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33c50 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23  tion_v2()]..*/.#
33c60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
33c70 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30  TERMINISTIC    0
33c80 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x800../*.** CAPI
33c90 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
33ca0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
33cb0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
33cc0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
33cd0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
33ce0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
33cf0 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
33d00 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
33d10 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
33d20 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
33d30 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
33d40 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
33d50 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
33d60 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
33d70 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
33d80 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
33d90 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f  ctions.  To enco
33da0 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72  urage programmer
33db0 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68  s to avoid.** th
33dc0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
33dd0 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61  e will not expla
33de0 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  in what they do.
33df0 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
33e00 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
33e10 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  ED.SQLITE_API SQ
33e20 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
33e30 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
33e40 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  LL sqlite3_aggre
33e50 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
33e60 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
33e70 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
33e80 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53  DEPRECATED int S
33e90 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
33ea0 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
33eb0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
33ec0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
33ed0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53  DEPRECATED int S
33ee0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
33ef0 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
33f00 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
33f10 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
33f20 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
33f30 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
33f40 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  TED int SQLITE_S
33f50 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67  TDCALL sqlite3_g
33f60 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
33f70 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
33f80 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
33f90 44 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  D void SQLITE_ST
33fa0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 68  DCALL sqlite3_th
33fb0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
33fc0 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  d);.SQLITE_API S
33fd0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
33fe0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
33ff0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ALL sqlite3_memo
34000 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
34010 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
34020 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20  nt64,int),.     
34030 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34040 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69   void*,sqlite3_i
34050 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
34060 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
34070 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c  btaining SQL Val
34080 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
34090 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
340a0 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
340b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
340c0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
340d0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
340e0 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
340f0 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
34100 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
34110 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
34120 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
34130 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
34140 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20  regate.  .**.** 
34150 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
34160 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
34170 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
34180 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
34190 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
341a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
341b0 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
341c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
341d0 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
341e0 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
341f0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
34200 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
34210 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
34220 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65  * The 3rd parame
34230 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
34240 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
34250 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
34260 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
34270 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
34280 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
34290 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
342a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
342b0 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
342c0 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
342d0 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
342e0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
342f0 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
34300 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
34310 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
34320 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
34330 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
34340 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
34350 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
34360 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
34370 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
34380 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
34390 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
343a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
343b0 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
343c0 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
343d0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
343e0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
343f0 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
34400 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
34410 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
34420 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
34430 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 74  ** except that t
34440 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
34450 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
34460 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
34470 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
34480 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
34490 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
344a0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
344b0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
344c0 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
344d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
344e0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
344f0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
34500 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
34510 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
34520 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
34530 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
34540 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
34550 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
34560 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
34570 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
34580 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
34590 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
345a0 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
345b0 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
345c0 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
345d0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
345e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
345f0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
34600 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
34610 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
34620 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
34630 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
34640 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
34650 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
34660 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
34670 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
34680 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
34690 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
346a0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
346b0 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
346c0 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
346d0 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
346e0 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
346f0 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
34700 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
34710 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
34720 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
34730 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
34740 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
34750 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
34760 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
34770 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
34780 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
34790 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
347a0 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
347b0 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
347c0 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
347d0 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
347e0 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
347f0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
34800 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
34810 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
34820 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
34830 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
34840 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
34850 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
34860 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
34870 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
34880 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
34890 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
348a0 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
348b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
348c0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
348d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
348e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
348f0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
34900 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
34910 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
34920 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
34930 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
34940 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
34950 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
34960 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  rs..*/.SQLITE_AP
34970 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
34980 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
34990 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
349a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
349b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
349c0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
349d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
349e0 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
349f0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
34a00 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
34a10 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
34a20 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
34a30 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
34a40 41 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54  API double SQLIT
34a50 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
34a60 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
34a70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34a80 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
34a90 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
34aa0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
34ab0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34ac0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
34ad0 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45  te3_int64 SQLITE
34ae0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
34af0 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
34b00 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
34b10 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75  LITE_API const u
34b20 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51  nsigned char *SQ
34b30 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
34b40 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
34b50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34b60 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
34b70 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  t void *SQLITE_S
34b80 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
34b90 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
34ba0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
34bb0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
34bc0 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
34bd0 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
34be0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
34bf0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34c00 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
34c10 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
34c20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
34c30 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
34c40 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
34c50 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
34c60 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
34c70 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
34c80 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34c90 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
34ca0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
34cb0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
34cc0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
34cd0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
34ce0 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20 46  3REF: Copy And F
34cf0 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a  ree SQL Values.*
34d00 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
34d10 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54  3_value.**.** ^T
34d20 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
34d30 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63  _dup(V) interfac
34d40 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
34d50 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
34d60 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
34d70 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  D and returns a 
34d80 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
34d90 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c  copy.  ^The [sql
34da0 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74 75  ite3_value] retu
34db0 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72  rned.** is a [pr
34dc0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
34dd0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65 76  value] object ev
34de0 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74 20  en if the input 
34df0 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20  is not..** ^The 
34e00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
34e10 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 72  p(V) interface r
34e20 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56  eturns NULL if V
34e30 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61   is NULL or if a
34e40 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
34e50 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a  ation fails..**.
34e60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34e70 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 6e  value_free(V) in
34e80 74 65 72 66 61 63 65 20 66 72 65 65 73 20 61 6e  terface frees an
34e90 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34ea0 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69   object.** previ
34eb0 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
34ec0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
34ed0 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66 20  ue_dup()].  ^If 
34ee0 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  V is a NULL poin
34ef0 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  ter.** then sqli
34f00 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56  te3_value_free(V
34f10 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  ) is a harmless 
34f20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45  no-op..*/.SQLITE
34f30 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45  _API SQLITE_EXPE
34f40 52 49 4d 45 4e 54 41 4c 20 73 71 6c 69 74 65 33  RIMENTAL sqlite3
34f50 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53  _value *SQLITE_S
34f60 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
34f70 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73  alue_dup(const s
34f80 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34f90 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
34fa0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
34fb0 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
34fc0 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
34fd0 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61  _free(sqlite3_va
34fe0 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
34ff0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
35000 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
35010 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54  n Context.** MET
35020 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
35030 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65  text.**.** Imple
35040 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67  mentations of ag
35050 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
35060 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a  tions use this.*
35070 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  * routine to all
35080 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72  ocate memory for
35090 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
350a0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tate..**.** ^The
350b0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
350c0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
350d0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
350e0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
350f0 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69   .** for a parti
35100 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20  cular aggregate 
35110 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65  function, SQLite
35120 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20  .** allocates N 
35130 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65  of memory, zeroe
35140 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72  s out that memor
35150 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
35160 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
35170 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e  he new memory. ^
35180 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  On second and su
35190 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
351a0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67  o.** sqlite3_agg
351b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
351c0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67   for the same ag
351d0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
351e0 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68   instance,.** th
351f0 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
35200 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69   returned.  Sqli
35210 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
35220 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61  ntext() is norma
35230 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e  lly.** called on
35240 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f  ce for each invo
35250 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53  cation of the xS
35260 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64  tep callback and
35270 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73   then one.** las
35280 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  t time when the 
35290 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
352a0 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57  is invoked.  ^(W
352b0 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63  hen no rows matc
352c0 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74  h.** an aggregat
352d0 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74  e query, the xSt
352e0 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ep() callback of
352f0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66   the aggregate f
35300 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65  unction.** imple
35310 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76  mentation is nev
35320 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46  er called and xF
35330 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64  inal() is called
35340 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a   exactly once..*
35350 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73  * In those cases
35360 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  , sqlite3_aggreg
35370 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69  ate_context() mi
35380 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f  ght be called fo
35390 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  r the.** first t
353a0 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  ime from within 
353b0 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a  xFinal().)^.**.*
353c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61  * ^The sqlite3_a
353d0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
353e0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65  (C,N) routine re
353f0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
35400 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69  nter .** when fi
35410 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20  rst called if N 
35420 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  is less than or 
35430 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
35440 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20   if a memory.** 
35450 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f  allocate error o
35460 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ccurs..**.** ^(T
35470 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61  he amount of spa
35480 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ce allocated by 
35490 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
354a0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69  e_context(C,N) i
354b0 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20  s.** determined 
354c0 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  by the N paramet
354d0 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63  er on first succ
354e0 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68  essful call.  Ch
354f0 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61  anging the.** va
35500 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73  lue of N in subs
35510 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
35520 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
35530 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69  _context() withi
35540 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67  n.** the same ag
35550 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
35560 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e   instance will n
35570 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65  ot resize the me
35580 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
35590 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68  on.)^  Within th
355a0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
355b0 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61  k, it is customa
355c0 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30  ry to set.** N=0
355d0 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c   in calls to sql
355e0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
355f0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74  ontext(C,N) so t
35600 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74  hat no .** point
35610 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  less memory allo
35620 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a  cations occur..*
35630 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
35640 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
35650 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
35660 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
35670 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
35680 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
35690 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
356a0 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
356b0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
356c0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
356d0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
356e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
356f0 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
35700 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
35710 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
35720 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
35730 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
35740 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
35750 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
35760 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
35770 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
35780 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
35790 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
357a0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
357b0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
357c0 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
357d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
357e0 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
357f0 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  PI void *SQLITE_
35800 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
35810 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
35820 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
35830 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
35840 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35850 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
35860 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  Functions.** MET
35870 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
35880 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  text.**.** ^The 
35890 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
358a0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
358b0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
358c0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
358d0 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
358e0 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
358f0 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
35900 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
35910 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35920 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
35930 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35940 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
35950 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
35960 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
35970 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
35980 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
35990 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
359a0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
359b0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
359c0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
359d0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
359e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
359f0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
35a00 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
35a10 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49  E_API void *SQLI
35a20 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
35a30 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
35a40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
35a50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35a60 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
35a70 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
35a80 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
35a90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
35aa0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35ab0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
35ac0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
35ad0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
35ae0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
35af0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
35b00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
35b10 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
35b20 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
35b30 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35b40 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
35b50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35b60 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
35b70 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
35b80 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
35b90 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
35ba0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
35bb0 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
35bc0 50 49 20 73 71 6c 69 74 65 33 20 2a 53 51 4c 49  PI sqlite3 *SQLI
35bd0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
35be0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
35bf0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
35c00 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
35c10 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
35c20 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
35c30 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
35c40 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
35c50 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
35c60 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
35c70 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29   (non-aggregate)
35c80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
35c90 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
35ca0 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
35cb0 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
35cc0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
35cd0 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
35ce0 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
35cf0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
35d00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
35d10 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
35d20 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
35d30 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
35d40 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
35d50 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
35d60 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20   preserved.  An 
35d70 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68  example.** of wh
35d80 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62  ere this might b
35d90 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61  e useful is in a
35da0 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
35db0 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20  ion matching.** 
35dc0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
35dd0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
35de0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
35df0 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
35e00 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
35e10 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
35e20 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72   with the patter
35e30 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54  n string.  .** T
35e40 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  hen as long as t
35e50 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
35e60 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61  g remains the sa
35e70 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69  me,.** the compi
35e80 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
35e90 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
35ea0 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
35eb0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
35ec0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
35ed0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
35ee0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
35ef0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
35f00 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
35f10 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
35f20 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
35f30 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
35f40 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
35f50 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
35f60 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
35f70 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
35f80 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35f90 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74   function. ^If t
35fa0 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64  here is no metad
35fb0 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
35fc0 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74  d with the funct
35fd0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68  ion argument, th
35fe0 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  is sqlite3_get_a
35ff0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
36000 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ce.** returns a 
36010 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
36020 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36030 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
36040 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20  ,P,X) interface 
36050 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64  saves P as metad
36060 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
36070 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
36080 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
36090 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
360a0 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a  .  ^Subsequent.*
360b0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
360c0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43  e3_get_auxdata(C
360d0 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f  ,N) return P fro
360e0 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  m the most recen
360f0 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  t.** sqlite3_set
36100 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
36110 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65  ) call if the me
36120 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20  tadata is still 
36130 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c  valid or.** NULL
36140 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
36150 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72   has been discar
36160 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65  ded..** ^After e
36170 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
36180 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
36190 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58  C,N,P,X) where X
361a0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
361b0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
361c0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
361d0 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69  or function X wi
361e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65  th parameter P e
361f0 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20  xactly.** once, 
36200 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74  when the metadat
36210 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a  a is discarded..
36220 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
36230 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65  e to discard the
36240 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79   metadata at any
36250 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67   time, including
36260 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77  : <ul>.** <li> w
36270 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
36280 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
36290 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
362a0 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  , or.** <li> whe
362b0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
362c0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
362d0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
362e0 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
362f0 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
36300 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ent, or.** <li> 
36310 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74  when sqlite3_set
36320 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e  _auxdata() is in
36330 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  voked again on t
36340 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65  he same paramete
36350 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75  r, or.** <li> du
36360 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ring the origina
36370 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  l sqlite3_set_au
36380 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65  xdata() call whe
36390 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20  n a memory .**  
363a0 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65      allocation e
363b0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75  rror occurs. </u
363c0 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  l>)^.**.** Note 
363d0 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20  the last bullet 
363e0 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20  in particular.  
363f0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58  The destructor X
36400 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   in .** sqlite3_
36410 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
36420 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61  P,X) might be ca
36430 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  lled immediately
36440 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20  , before the.** 
36450 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
36460 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
36470 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48  even returns.  H
36480 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ence sqlite3_set
36490 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68  _auxdata().** sh
364a0 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e  ould be called n
364b0 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ear the end of t
364c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
364d0 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74  ementation and t
364e0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  he.** function i
364f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
36500 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e  ould not make an
36510 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72  y use of P after
36520 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
36530 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65  auxdata() has be
36540 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a  en called..**.**
36550 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
36560 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
36570 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
36580 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
36590 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
365a0 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
365b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f   compile-time co
365c0 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69  nstants, includi
365d0 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  ng literal.** va
365e0 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
365f0 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73  ters] and expres
36600 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66  sions composed f
36610 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a  rom the same.)^.
36620 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
36630 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
36640 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
36650 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
36660 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
36670 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
36680 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
36690 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
366a0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 65 74  CALL sqlite3_get
366b0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
366c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
366d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
366e0 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  id SQLITE_STDCAL
366f0 4c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  L sqlite3_set_au
36700 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
36710 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
36720 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
36730 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
36740 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
36750 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
36760 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
36770 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
36780 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
36790 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
367a0 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
367b0 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
367c0 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
367d0 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
367e0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
367f0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
36800 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63   ^If the destruc
36810 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
36820 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
36830 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
36840 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
36850 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
36860 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
36870 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
36880 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
36890 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54  e destroyed.  ^T
368a0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
368b0 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
368c0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
368d0 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
368e0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
368f0 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
36900 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
36910 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
36920 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
36930 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
36940 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
36950 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
36960 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
36970 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
36980 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
36990 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
369a0 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  lers..*/.typedef
369b0 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
369c0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
369d0 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
369e0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
369f0 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
36a00 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
36a10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36a20 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
36a30 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
36a40 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
36a50 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
36a60 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
36a70 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
36a80 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
36a90 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
36aa0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
36ab0 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
36ac0 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
36ad0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
36ae0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
36af0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
36b00 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
36b10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
36b20 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
36b30 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
36b40 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
36b50 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
36b60 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
36b70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
36b80 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
36b90 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70  much like the [p
36ba0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
36bb0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66  ] family of.** f
36bc0 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f  unctions used to
36bd0 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
36be0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
36bf0 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
36c00 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
36c10 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72   to the [SQL par
36c20 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74  ameter] document
36c30 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
36c40 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
36c50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36c60 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
36c70 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
36c80 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
36c90 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
36ca0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
36cb0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
36cc0 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
36cd0 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
36ce0 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
36cf0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
36d00 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
36d10 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
36d20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
36d30 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
36d40 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36d50 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 61 6e 64  t_zeroblob() and
36d60 20 7a 65 72 6f 62 6c 6f 62 36 34 28 29 20 69 6e   zeroblob64() in
36d70 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
36d80 20 72 65 73 75 6c 74 20 0a 2a 2a 20 6f 66 20 74   result .** of t
36d90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
36da0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36db0 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
36dc0 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
36dd0 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
36de0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
36df0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
36e00 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
36e10 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
36e20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36e30 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
36e40 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
36e50 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
36e60 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
36e70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
36e80 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
36e90 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
36ea0 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
36eb0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
36ec0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36ed0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
36ee0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
36ef0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
36f00 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
36f10 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
36f20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
36f30 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
36f40 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  on..** ^SQLite u
36f50 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
36f60 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
36f70 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
36f80 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
36f90 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
36fa0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36fb0 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
36fc0 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
36fd0 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51  or message.  ^SQ
36fe0 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
36ff0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
37000 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
37010 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37020 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
37030 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  . ^SQLite.** int
37040 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
37050 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
37060 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
37070 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
37080 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
37090 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69  er.  ^If the thi
370a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
370b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
370c0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
370d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
370e0 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
370f0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
37100 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
37110 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
37120 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
37130 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
37140 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
37150 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
37160 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
37170 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
37180 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
37190 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
371a0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
371b0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
371c0 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
371d0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
371e0 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
371f0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
37200 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
37210 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37220 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
37230 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
37240 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
37250 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
37260 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
37270 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
37280 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
37290 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
372a0 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
372b0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
372c0 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
372d0 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
372e0 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
372f0 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
37300 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37310 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
37320 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
37330 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
37340 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
37350 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
37360 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
37370 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
37380 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a    ^By default,.*
37390 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
373a0 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
373b0 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74  .  ^A subsequent
373c0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
373d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
373e0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
373f0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
37400 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
37410 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
37420 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  RROR..**.** ^The
37430 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37440 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69  error_toobig() i
37450 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
37460 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
37470 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
37480 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
37490 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
374a0 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
374b0 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
374c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
374d0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69  _error_nomem() i
374e0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
374f0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
37500 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
37510 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
37520 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
37530 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
37540 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37550 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
37560 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
37570 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
37580 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
37590 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
375a0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
375b0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
375c0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
375d0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
375e0 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
375f0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
37600 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
37610 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
37620 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
37630 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
37640 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
37650 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
37660 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
37670 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
37680 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
37690 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
376a0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
376b0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
376c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
376d0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
376e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
376f0 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
37700 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37710 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
37720 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
37730 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
37740 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37750 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
37760 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37770 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
37780 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
37790 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
377a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
377b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
377c0 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
377d0 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
377e0 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
377f0 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
37800 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
37810 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
37820 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
37830 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
37840 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
37850 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37860 6c 74 5f 74 65 78 74 36 34 28 29 20 69 6e 74 65  lt_text64() inte
37870 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
37880 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61  eturn value of a
37890 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  n.** application
378a0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
378b0 6e 20 74 6f 20 62 65 20 61 20 74 65 78 74 20 73  n to be a text s
378c0 74 72 69 6e 67 20 69 6e 20 61 6e 20 65 6e 63 6f  tring in an enco
378d0 64 69 6e 67 0a 2a 2a 20 73 70 65 63 69 66 69 65  ding.** specifie
378e0 64 20 62 79 20 74 68 65 20 66 69 66 74 68 20 28  d by the fifth (
378f0 61 6e 64 20 6c 61 73 74 29 20 70 61 72 61 6d 65  and last) parame
37900 74 65 72 2c 20 77 68 69 63 68 20 6d 75 73 74 20  ter, which must 
37910 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51  be one.** of [SQ
37920 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
37930 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
37940 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
37950 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
37960 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61  ]..** ^SQLite ta
37970 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
37980 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
37990 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
379a0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
379b0 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
379c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
379d0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49  nterfaces..** ^I
379e0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
379f0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
37a00 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
37a10 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
37a20 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
37a30 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
37a40 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
37a50 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
37a60 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
37a70 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
37a80 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
37a90 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
37aa0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
37ab0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
37ac0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
37ad0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
37ae0 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
37af0 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
37b00 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
37b10 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
37b20 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
37b30 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
37b40 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37b50 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
37b60 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 64  ult.  If the 3rd
37b70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
37b80 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
37b90 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74   it.** must be t
37ba0 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 69  he byte offset i
37bb0 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77  nto the string w
37bc0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
37bd0 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a  minator would.**
37be0 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20 73   appear if the s
37bf0 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20  tring where NUL 
37c00 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
37c10 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
37c20 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  rs occur.** in t
37c30 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 62  he string at a b
37c40 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 20  yte offset that 
37c50 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  is less than the
37c60 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72   value of the 3r
37c70 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20  d.** parameter, 
37c80 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
37c90 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63  ng string will c
37ca0 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
37cb0 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  NULs and the.** 
37cc0 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
37cd0 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20  sions operating 
37ce0 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 20  on strings with 
37cf0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
37d00 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
37d10 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
37d20 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
37d30 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
37d40 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
37d50 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
37d60 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
37d70 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
37d80 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
37d90 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
37da0 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
37db0 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
37dc0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
37dd0 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
37de0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
37df0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
37e00 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
37e10 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
37e20 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
37e30 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a  erfaces or to.**
37e40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37e50 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
37e60 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
37e70 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
37e80 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
37e90 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
37ea0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
37eb0 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
37ec0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
37ed0 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f  t.** copy the co
37ee0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72  ntent of the par
37ef0 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20  ameter nor call 
37f00 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  a destructor on 
37f10 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77  the content.** w
37f20 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
37f30 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
37f40 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
37f50 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
37f60 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
37f70 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
37f80 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
37f90 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
37fa0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
37fb0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
37fc0 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
37fd0 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
37fe0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
37ff0 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
38000 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
38010 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
38020 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
38030 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
38040 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
38050 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
38060 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
38070 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
38080 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
38090 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
380a0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
380b0 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
380c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
380d0 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
380e0 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
380f0 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
38100 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38110 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
38120 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
38130 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
38140 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
38150 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
38160 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
38170 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
38180 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
38190 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
381a0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
381b0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
381c0 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
381d0 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
381e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
381f0 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
38200 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
38210 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
38220 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
38230 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
38240 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
38250 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
38260 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
38270 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
38280 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
38290 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
382a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
382b0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
382c0 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
382d0 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
382e0 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
382f0 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
38300 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
38310 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
38320 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
38330 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
38340 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
38350 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
38360 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
38370 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
38380 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  LL sqlite3_resul
38390 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
383a0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
383b0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
383c0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
383d0 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49  TE_API void SQLI
383e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
383f0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 36 34  e3_result_blob64
38400 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38410 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 0a 20  *,const void*,. 
38420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38430 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
38440 33 5f 75 69 6e 74 36 34 2c 76 6f 69 64 28 2a 29  3_uint64,void(*)
38450 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
38460 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
38470 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
38480 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73  _result_double(s
38490 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
384a0 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45   double);.SQLITE
384b0 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
384c0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
384d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
384e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
384f0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
38500 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
38510 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  id SQLITE_STDCAL
38520 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  L sqlite3_result
38530 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
38540 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
38550 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51   void*, int);.SQ
38560 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
38570 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
38580 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
38590 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
385a0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
385b0 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49  TE_API void SQLI
385c0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
385d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
385e0 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
385f0 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
38600 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f  API void SQLITE_
38610 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
38620 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
38630 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
38640 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
38650 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
38660 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
38670 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
38680 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
38690 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
386a0 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
386b0 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  LL sqlite3_resul
386c0 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
386d0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
386e0 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  3_int64);.SQLITE
386f0 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
38700 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
38710 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c  _result_null(sql
38720 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
38730 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
38740 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
38750 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
38760 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
38770 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
38780 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
38790 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
3