System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact a41446e48e7bfdcb052e1773572ad7bc662c68e1:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 33 2e 31 33 2e 30 22 0a 23 64       "3.13.0".#d
10b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
10c0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 31 33  SION_NUMBER 3013
10d0: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
10e0: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20  TE_SOURCE_ID    
10f0: 20 20 22 32 30 31 36 2d 30 35 2d 31 38 20 31 30    "2016-05-18 10
1100: 3a 35 37 3a 33 30 20 66 63 34 39 66 35 35 36 65  :57:30 fc49f556e
1110: 34 38 39 37 30 35 36 31 64 37 61 62 36 61 32 66  48970561d7ab6a2f
1120: 32 34 66 64 64 37 64 39 65 62 38 31 66 66 32 22  24fdd7d9eb81ff2"
1130: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1140: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
1150: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
1160: 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
1170: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c  sqlite3_version,
1180: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
1190: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
11a0: 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65  terfaces provide
11b0: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
11c0: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51  ation as the [SQ
11d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a  LITE_VERSION],.*
11e0: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
11f0: 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b  N_NUMBER], and [
1200: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1210: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1220: 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61   macros.** but a
1230: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  re associated wi
1240: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
1250: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
1260: 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61  ader file.  ^(Ca
1270: 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61  utious.** progra
1280: 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c  mmers might incl
1290: 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61  ude assert() sta
12a0: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72  tements in their
12b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
12c0: 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76  ** verify that v
12d0: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
12e0: 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  y these interfac
12f0: 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63  es match the mac
1300: 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65  ros in.** the he
1310: 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65  ader, and thus e
1320: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
1330: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a  pplication is.**
1340: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1350: 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20  atching library 
1360: 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73  and header files
1370: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  ..**.** <blockqu
1380: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73  ote><pre>.** ass
1390: 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62  ert( sqlite3_lib
13a0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
13b0: 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ==SQLITE_VERSION
13c0: 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73  _NUMBER );.** as
13d0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
13e0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c  ite3_sourceid(),
13f0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1400: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1410: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1420: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1430: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1440: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1450: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1460: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1470: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1480: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
1490: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
14a0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
14b0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
14c0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14d0: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
14e0: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
14f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1500: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1510: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1520: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1530: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1540: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1550: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
1560: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
1570: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
1580: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
1590: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
15a0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
15b0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
15c0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
15d0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
15e0: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
15f0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1600: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1610: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1620: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  BER].  ^The sqli
1630: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66  te3_sourceid() f
1640: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1650: 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
1660: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61   a string consta
1670: 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69  nt whose value i
1680: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68  s the same as th
1690: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  e .** [SQLITE_SO
16a0: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
16b0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a  ocessor macro..*
16c0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
16d0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
16e0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
16f0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
1700: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1710: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
1720: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
1730: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49  on[];.SQLITE_API
1740: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1750: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1760: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76  te3_libversion(v
1770: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
1780: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1790: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
17a0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69  te3_sourceid(voi
17b0: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
17c0: 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
17d0: 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  L sqlite3_libver
17e0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
17f0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1800: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
1810: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
1820: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1830: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1840: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1850: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1860: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
1870: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
1880: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
1890: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
18a0: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
18b0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
18c0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
18d0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
18e0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
18f0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
1900: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
1910: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
1920: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1930: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1940: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1950: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1960: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
1970: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
1980: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
1990: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
19a0: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
19b0: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
19c0: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
19d0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
19e0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
19f0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
1a00: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1a10: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
1a20: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1a30: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1a40: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1a50: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1a60: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1a70: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1a80: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
1a90: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
1aa0: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
1ab0: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
1ac0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1ad0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
1ae0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1af0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
1b00: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
1b10: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
1b20: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1b30: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1b40: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1b50: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1b60: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1b70: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1b80: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1b90: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1ba0: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1bb0: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1bc0: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1bd0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1be0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1bf0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1c00: 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49  DIAGS.SQLITE_API
1c10: 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1c20: 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ALL sqlite3_comp
1c30: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63  ileoption_used(c
1c40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e  onst char *zOptN
1c50: 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ame);.SQLITE_API
1c60: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1c70: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1c80: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1c90: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1ca0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1cb0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1cc0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1cd0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1ce0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1cf0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1d00: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1d10: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1d20: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1d30: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1d40: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1d50: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1d60: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1d70: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1d80: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1d90: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1da0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1db0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1dc0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1dd0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1de0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1df0: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1e00: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1e10: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1e20: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1e30: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1e40: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1e50: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e60: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1e70: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1e80: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1e90: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1ea0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1eb0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1ec0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1ed0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1ee0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1ef0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1f00: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1f10: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1f20: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1f30: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1f40: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1f50: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1f60: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1f70: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1f80: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1f90: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1fa0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1fb0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1fc0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1fd0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
1fe0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
1ff0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2000: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
2010: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
2020: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
2030: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
2040: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
2050: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
2060: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
2070: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
2080: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
2090: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
20a0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
20b0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
20c0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
20d0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
20e0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
20f0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2100: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2110: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2120: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2130: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2140: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2150: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2160: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
2170: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
2180: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
2190: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
21a0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
21b0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
21c0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
21d0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
21e0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
21f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2200: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2210: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2220: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
2230: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
2240: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
2250: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2260: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2270: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2280: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2290: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
22a0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
22b0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
22c0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
22d0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
22e0: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
22f0: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2300: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
2310: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2320: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
2330: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
2340: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2350: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
2360: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2370: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2380: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2390: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23a0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
23b0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
23c0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
23d0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
23e0: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
23f0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
2400: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
2410: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2420: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
2430: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
2440: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
2450: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
2460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
2470: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
2480: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
2490: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
24a0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
24b0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
24c0: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
24d0: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
24e0: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
24f0: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
2500: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2510: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
2520: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
2530: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
2540: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
2550: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
2560: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
2570: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2580: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20  close_v2()] are 
2590: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e  its destructors.
25a0: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
25b0: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
25c0: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
25d0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25e0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
25f0: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2600: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
2610: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
2620: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
2630: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
2640: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
2650: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
2660: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
2670: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
2680: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
2690: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
26a0: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b  teger Types.** K
26b0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
26c0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
26d0: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
26e0: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
26f0: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
2700: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
2710: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
2720: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
2730: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
2740: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
2750: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
2760: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
2770: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
2780: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
2790: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
27a0: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
27b0: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
27c0: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
27d0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
27e0: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
27f0: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
2800: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
2810: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
2820: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79   sqlite_int64 ty
2840: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
2850: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  teger values.** 
2860: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
2870: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
2880: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
2890: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e  75807 inclusive.
28a0: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
28b0: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  3_uint64 and sql
28c0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
28d0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
28e0: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65  er values .** be
28f0: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34  tween 0 and +184
2900: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31  4674407370955161
2910: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a  5 inclusive..*/.
2920: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
2930: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
2940: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2950: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
2960: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2970: 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54  igned SQLITE_INT
2980: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
2990: 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66  int64;.#elif def
29a0: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c  ined(_MSC_VER) |
29b0: 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c  | defined(__BORL
29c0: 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65  ANDC__).  typede
29d0: 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  f __int64 sqlite
29e0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
29f0: 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74  f unsigned __int
2a00: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2a10: 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65  ;.#else.  typede
2a20: 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  f long long int 
2a30: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
2a40: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
2a50: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
2a60: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2a70: 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c  ndif.typedef sql
2a80: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
2a90: 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66  3_int64;.typedef
2aa0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73   sqlite_uint64 s
2ab0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a  qlite3_uint64;..
2ac0: 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69  /*.** If compili
2ad0: 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73  ng for a process
2ae0: 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c  or that lacks fl
2af0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70  oating point sup
2b00: 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74  port,.** substit
2b10: 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20  ute integer for 
2b20: 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a  floating-point..
2b30: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
2b40: 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50  _OMIT_FLOATING_P
2b50: 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f  OINT.# define do
2b60: 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  uble sqlite3_int
2b70: 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  64.#endif../*.**
2b80: 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69   CAPI3REF: Closi
2b90: 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  ng A Database Co
2ba0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 54  nnection.** DEST
2bb0: 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a  RUCTOR: sqlite3.
2bc0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2bd0: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73  e3_close() and s
2be0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2bf0: 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  ) routines are d
2c00: 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f  estructors.** fo
2c10: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  r the [sqlite3] 
2c20: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c  object..** ^Call
2c30: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f  s to sqlite3_clo
2c40: 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  se() and sqlite3
2c50: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75  _close_v2() retu
2c60: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  rn [SQLITE_OK] i
2c70: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  f.** the [sqlite
2c80: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63  3] object is suc
2c90: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f  cessfully destro
2ca0: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f  yed and all asso
2cb0: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72  ciated.** resour
2cc0: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
2cd0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ted..**.** ^If t
2ce0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2cf0: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69  ection is associ
2d00: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61  ated with unfina
2d10: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a  lized prepared.*
2d20: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20  * statements or 
2d30: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
2d40: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74  e3_backup object
2d50: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  s then sqlite3_c
2d60: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c  lose().** will l
2d70: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73  eave the databas
2d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
2d90: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  n and return [SQ
2da0: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e  LITE_BUSY]..** ^
2db0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  If sqlite3_close
2dc0: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
2dd0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2de0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2df0: 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75  ents.** and/or u
2e00: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
2e10: 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20  3_backups, then 
2e20: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2e30: 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a  nection becomes.
2e40: 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22  ** an unusable "
2e50: 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69  zombie" which wi
2e60: 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
2e70: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
2e80: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74  when the.** last
2e90: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ea0: 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2eb0: 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c   or the last sql
2ec0: 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a  ite3_backup is.*
2ed0: 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65  * finished.  The
2ee0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2ef0: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
2f00: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
2f10: 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c  e with.** host l
2f20: 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72  anguages that ar
2f30: 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63  e garbage collec
2f40: 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74  ted, and where t
2f50: 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63  he order in whic
2f60: 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73  h.** destructors
2f70: 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61   are called is a
2f80: 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  rbitrary..**.** 
2f90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
2fa0: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  uld [sqlite3_fin
2fb0: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2fc0: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20  ] all [prepared 
2fd0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20  statements],.** 
2fe0: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
2ff0: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c  ose | close] all
3000: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
3010: 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
3020: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20  3_backup_finish 
3030: 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73  | finish] all [s
3040: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3050: 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65  bjects associate
3060: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73  d.** with the [s
3070: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
3080: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69  rior to attempti
3090: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
30a0: 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20  object.  ^If.** 
30b0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
30c0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  () is called on 
30d0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
30e0: 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69  ection] that sti
30f0: 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61  ll has.** outsta
3100: 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20  nding [prepared 
3110: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c  statements], [BL
3120: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3130: 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  /or.** [sqlite3_
3140: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3150: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20  then it returns 
3160: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20  [SQLITE_OK] and 
3170: 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e  the deallocation
3180: 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73  .** of resources
3190: 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e 74   is deferred unt
31a0: 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64  il all [prepared
31b0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42   statements], [B
31c0: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a  LOB handles],.**
31d0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61   and [sqlite3_ba
31e0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72  ckup] objects ar
31f0: 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64  e also destroyed
3200: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b  ..**.** ^If an [
3210: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
3220: 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68 69  is destroyed whi
3230: 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  le a transaction
3240: 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65   is open,.** the
3250: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3260: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
3270: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
3280: 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72   The C parameter
3290: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
32a0: 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69  se(C)] and [sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d  te3_close_v2(C)]
32c0: 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
32d0: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
32e0: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
32f0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
3300: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
3310: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
3320: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
3330: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
3340: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
3350: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
3360: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
3370: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
3380: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20  ite3_close() or 
3390: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
33a0: 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  () with a NULL p
33b0: 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65  ointer.** argume
33c0: 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  nt is a harmless
33d0: 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54   no-op..*/.SQLIT
33e0: 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
33f0: 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
3400: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29  _close(sqlite3*)
3410: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
3420: 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3440: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3450: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3460: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
3470: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
3480: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
3490: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
34a0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
34b0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
34c0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
34d0: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
34e0: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
34f0: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
3500: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
3510: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
3520: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
3530: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
3540: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3550: 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
3560: 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
3570: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3580: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
3590: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
35a0: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
35b0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
35c0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
35d0: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
35e0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20  finalize()],.** 
35f0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
3600: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75  pplication to ru
3610: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65  n multiple state
3620: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20  ments of SQL.** 
3630: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
3640: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43  o use a lot of C
3650: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54   code. .**.** ^T
3660: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3670: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73  ) interface runs
3680: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54   zero or more UT
3690: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20  F-8 encoded,.** 
36a0: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
36b0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
36c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74  s passed into it
36d0: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a  s 2nd argument,.
36e0: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ** in the contex
36f0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
3700: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
3710: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20  assed in as its 
3720: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  1st.** argument.
3730: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
3740: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74  ck function of t
3750: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3760: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
3770: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
3780: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76  , then it is inv
3790: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65  oked for each re
37a0: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69  sult row.** comi
37b0: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76  ng out of the ev
37c0: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74  aluated SQL stat
37d0: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74  ements.  ^The 4t
37e0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  h argument to.**
37f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3800: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75  is relayed throu
3810: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72  gh to the 1st ar
3820: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a  gument of each.*
3830: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63  * callback invoc
3840: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20  ation.  ^If the 
3850: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72  callback pointer
3860: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3870: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  ().** is NULL, t
3880: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20  hen no callback 
3890: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20  is ever invoked 
38a0: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20  and result rows 
38b0: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a  are.** ignored..
38c0: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  **.** ^If an err
38d0: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
38e0: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53  evaluating the S
38f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
3900: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  ssed into.** sql
3910: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65  ite3_exec(), the
3920: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  n execution of t
3930: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
3940: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a  ment stops and.*
3950: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61  * subsequent sta
3960: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70  tements are skip
3970: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74  ped.  ^If the 5t
3980: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3990: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
39a0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
39b0: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  n any error mess
39c0: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
39d0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
39e0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
39f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
3a00: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  nd passed back t
3a10: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3a20: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20  arameter..** To 
3a30: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61  avoid memory lea
3a40: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ks, the applicat
3a50: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b  ion should invok
3a60: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
3a70: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d  )].** on error m
3a80: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72  essage strings r
3a90: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
3aa0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3ab0: 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r of.** sqlite3_
3ac0: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
3ad0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3ae0: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3af0: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3b00: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3b10: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3b20: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3b30: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3b40: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3b60: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
3b70: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
3b80: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
3b90: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
3ba0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
3bb0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3bc0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
3bd0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3be0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3bf0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3c00: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3c10: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3c20: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
3c30: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
3c40: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
3c50: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3c60: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
3c70: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
3c80: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3c90: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3ca0: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3cb0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3cc0: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3cd0: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3ce0: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3cf0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3d00: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3d10: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3d20: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
3d30: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
3d40: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3d50: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
3d60: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
3d70: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
3d80: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3d90: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3da0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3db0: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3dc0: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3dd0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3de0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3df0: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3e00: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3e10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3e20: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3e30: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3e40: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
3e50: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
3e60: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
3e70: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
3e80: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3e90: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3ea0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3eb0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3ec0: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3ed0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3ee0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3ef0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3f00: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3f10: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3f20: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
3f30: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
3f40: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
3f50: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
3f60: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
3f70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
3f80: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3f90: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3fa0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3fb0: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3fc0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3fd0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3fe0: 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72  ation must ensur
3ff0: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
4000: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4010: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
4020: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
4030: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
4040: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
4050: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
4060: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
4070: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
4080: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
4090: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
40a0: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
40b0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
40c0: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
40d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
40e0: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <li>
40f0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
4100: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
4110: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
4120: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
4130: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
4140: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
4150: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4160: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
4170: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
4180: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c  .** </ul>.*/.SQL
4190: 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
41a0: 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
41b0: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
41c0: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
41f0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
4200: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
4210: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4220: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
4230: 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
4240: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
4250: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
4260: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
4270: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
4280: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
4290: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
42c0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
42d0: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
42e0: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4300: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
4310: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
4320: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
4330: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  F: Result Codes.
4340: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65  ** KEYWORDS: {re
4350: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4360: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  tions}.**.** Man
4370: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
4380: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
4390: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
43a0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
43b0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
43c0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
43d0: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
43e0: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
43f0: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4400: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4410: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4420: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4430: 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20  also: [extended 
4440: 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69  result code defi
4450: 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66  nitions].*/.#def
4460: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
4470: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
4480: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
4490: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
44a0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
44b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
44c0: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
44d0: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
44e0: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
44f0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4500: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
4510: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
4520: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
4530: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
4540: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
4550: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
4560: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
4570: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4580: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
4590: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
45a0: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
45b0: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
45c0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
45d0: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
45e0: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
45f0: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
4600: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4610: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
4620: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
4630: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
4640: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
4650: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4660: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
4670: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
4680: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
4690: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
46a0: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
46b0: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
46c0: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
46d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46e0: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
46f0: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
4700: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
4710: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
4720: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4730: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
4740: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
4750: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
4760: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
4770: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
4780: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
4790: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
47a0: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
47b0: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
47c0: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
47d0: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
47e0: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
47f0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
4800: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
4810: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
4820: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
4830: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
4840: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
4850: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
4860: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
4870: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
4880: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
4890: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
48a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
48b0: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
48c0: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
48d0: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
48e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
48f0: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
4900: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
4910: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
4920: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
4930: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
4940: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
4950: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
4960: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
4970: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
4980: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
4990: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
49a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
49b0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
49c0: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
49d0: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
49e0: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
49f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
4a00: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
4a10: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
4a20: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
4a30: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
4a40: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
4a50: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
4a60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a70: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
4a80: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
4a90: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
4aa0: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
4ab0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ac0: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
4ad0: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
4ae0: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4af0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
4b00: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
4b10: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
4b20: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
4b30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b40: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
4b50: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
4b60: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
4b70: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
4b80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b90: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
4ba0: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
4bb0: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
4bc0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
4bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4be0: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20  NOTICE      27  
4bf0: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e   /* Notification
4c00: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4c10: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4c20: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20  SQLITE_WARNING  
4c30: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69     28   /* Warni
4c40: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ngs from sqlite3
4c50: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
4c60: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4c70: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4c80: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4c90: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4ca0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4cb0: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4cc0: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4cd0: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4ce0: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4cf0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4d00: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4d10: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4d20: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4d30: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4d40: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4d50: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d  ode definitions}
4d60: 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65  .**.** In its de
4d70: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
4d80: 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20  ion, SQLite API 
4d90: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
4da0: 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65  one of 30 intege
4db0: 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64  r.** [result cod
4dc0: 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65  es].  However, e
4dd0: 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68  xperience has sh
4de0: 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66  own that many of
4df0: 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74  .** these result
4e00: 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63   codes are too c
4e10: 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20  oarse-grained.  
4e20: 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76  They do not prov
4e30: 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69  ide as.** much i
4e40: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
4e50: 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f   problems as pro
4e60: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c  grammers might l
4e70: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f  ike.  In an effo
4e80: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73  rt to.** address
4e90: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72   this, newer ver
4ea0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
4eb0: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61  (version 3.3.8 a
4ec0: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
4ed0: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
4ee0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
4ef0: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
4f00: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
4f10: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
4f20: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
4f30: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64   These [extended
4f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
4f50: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4f60: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4f70: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4f80: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4f90: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4fa0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4fb0: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4fc0: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64    Or, the extend
4fd0: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74  ed code for.** t
4fe0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
4ff0: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61  rror can be obta
5000: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
5010: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
5020: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23  errcode()]..*/.#
5030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5040: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
5050: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5060: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
5070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5080: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
5090: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50a0: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
50b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
50c0: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
50d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
50e0: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
50f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5100: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  _FSYNC          
5110: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5120: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5140: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  DIR_FSYNC       
5150: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5160: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5170: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
5180: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20  RUNCATE         
5190: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51a0: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
51b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
51c0: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20  TAT             
51d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
51e0: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
51f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
5200: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
5210: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5220: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5230: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
5240: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5250: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
5260: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5270: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
5280: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  E            (SQ
5290: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
52a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
52c0: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ED           (SQ
52d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
52e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d  LITE_IOERR_NOMEM
5300: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5310: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32  LITE_IOERR | (12
5320: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5330: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53  LITE_IOERR_ACCES
5340: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  S            (SQ
5350: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33  LITE_IOERR | (13
5360: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5370: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b  LITE_IOERR_CHECK
5380: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51  RESERVEDLOCK (SQ
5390: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34  LITE_IOERR | (14
53a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
53b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20  LITE_IOERR_LOCK 
53c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
53d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35  LITE_IOERR | (15
53e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
53f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45  LITE_IOERR_CLOSE
5400: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5410: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36  LITE_IOERR | (16
5420: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5430: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43  LITE_IOERR_DIR_C
5440: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51  LOSE         (SQ
5450: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37  LITE_IOERR | (17
5460: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5470: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50  LITE_IOERR_SHMOP
5480: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51  EN           (SQ
5490: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38  LITE_IOERR | (18
54a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49  LITE_IOERR_SHMSI
54c0: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ZE           (SQ
54d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39  LITE_IOERR | (19
54e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f  LITE_IOERR_SHMLO
5500: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51  CK           (SQ
5510: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30  LITE_IOERR | (20
5520: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5530: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41  LITE_IOERR_SHMMA
5540: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  P            (SQ
5550: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31  LITE_IOERR | (21
5560: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5570: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20  LITE_IOERR_SEEK 
5580: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5590: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32  LITE_IOERR | (22
55a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
55b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
55c0: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51  E_NOENT      (SQ
55d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33  LITE_IOERR | (23
55e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
55f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20  LITE_IOERR_MMAP 
5600: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5610: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34  LITE_IOERR | (24
5620: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5630: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45  LITE_IOERR_GETTE
5640: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51  MPPATH       (SQ
5650: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35  LITE_IOERR | (25
5660: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5670: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50  LITE_IOERR_CONVP
5680: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51  ATH          (SQ
5690: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36  LITE_IOERR | (26
56a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
56b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45  LITE_IOERR_VNODE
56c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
56d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37  LITE_IOERR | (27
56e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
56f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20  LITE_IOERR_AUTH 
5700: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5710: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38  LITE_IOERR | (28
5720: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5730: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52  LITE_LOCKED_SHAR
5740: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51  EDCACHE      (SQ
5750: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28  LITE_LOCKED |  (
5760: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5770: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56  QLITE_BUSY_RECOV
5780: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53  ERY           (S
5790: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
57a0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
57b0: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50  SQLITE_BUSY_SNAP
57c0: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28  SHOT           (
57d0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
57e0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
57f0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5800: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20  _NOTEMPDIR      
5810: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5820: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5830: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5840: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20  EN_ISDIR        
5850: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5860: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  EN | (2<<8)).#de
5870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5880: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20  OPEN_FULLPATH   
5890: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
58a0: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OPEN | (3<<8)).#
58b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
58c0: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20  NTOPEN_CONVPATH 
58d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
58e0: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29  NTOPEN | (4<<8))
58f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5900: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5910: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5920: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
5930: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5940: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
5950: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
5960: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
5970: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5980: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
5990: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
59a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
59b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
59c0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
59d0: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
59e0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
59f0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5a00: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5a10: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28  DBMOVED        (
5a20: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5a30: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5a40: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
5a50: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
5a60: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
5a70: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5a80: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5a90: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
5aa0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5ab0: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
5ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5ad0: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
5ae0: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
5af0: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
5b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b10: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
5b20: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
5b30: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
5b40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5b60: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
5b70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5b80: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5b90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ba0: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
5bb0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5bc0: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
5bd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5be0: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
5bf0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5c00: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
5c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c20: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
5c30: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
5c40: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
5c50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5c60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
5c70: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
5c80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5c90: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5ca0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5cb0: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
5cc0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5cd0: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
5ce0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5cf0: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20  TRAINT_ROWID    
5d00: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5d10: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29  TRAINT |(10<<8))
5d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d30: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57  NOTICE_RECOVER_W
5d40: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  AL      (SQLITE_
5d50: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29  NOTICE | (1<<8))
5d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d70: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52  NOTICE_RECOVER_R
5d80: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f  OLLBACK (SQLITE_
5d90: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29  NOTICE | (2<<8))
5da0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5db0: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45  WARNING_AUTOINDE
5dc0: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  X       (SQLITE_
5dd0: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29  WARNING | (1<<8)
5de0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5df0: 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20  _AUTH_USER      
5e00: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5e10: 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a  _AUTH | (1<<8)).
5e20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5e30: 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20   Flags For File 
5e40: 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a  Open Operations.
5e50: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20  **.** These bit 
5e60: 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e  values are inten
5e70: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74  ded for use in t
5e80: 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65  he.** 3rd parame
5e90: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
5ea0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
5eb0: 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20  nterface and.** 
5ec0: 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  in the 4th param
5ed0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
5ee0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
5ef0: 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69  method..*/.#defi
5f00: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5f10: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
5f20: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
5f30: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5f40: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5f50: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5f60: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
5f70: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
5f80: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5f90: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5fa0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
5fb0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
5fc0: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
5fd0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5fe0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5ff0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
6000: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
6010: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
6020: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6030: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
6040: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
6050: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
6060: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6070: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
6080: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
6090: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
60a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
60b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  ne SQLITE_OPEN_U
60c0: 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RI              
60d0: 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f  0x00000040  /* O
60e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
60f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6100: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6110: 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20 20  EMORY           
6120: 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f  0x00000080  /* O
6130: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6140: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6150: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6160: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
6170: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
6180: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6190: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
61a0: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
61b0: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
61c0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
61d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
61e0: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
61f0: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
6200: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6210: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6220: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
6230: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
6240: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6250: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
6260: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
6270: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
6280: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6290: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
62a0: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
62b0: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
62c0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
62d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
62e0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
62f0: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
6300: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6310: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
6320: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
6330: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
6340: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6350: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6360: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
6370: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
6380: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
6390: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
63a0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
63b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
63c0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
63d0: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
63e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
63f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
6410: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
6420: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
6430: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6440: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6450: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57  ne SQLITE_OPEN_W
6460: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AL              
6470: 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56  0x00080000  /* V
6480: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52  FS only */../* R
6490: 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20  eserved:        
64a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
64b0: 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a   0x00F00000 */..
64c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
64d0: 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72  Device Character
64e0: 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65  istics.**.** The
64f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
6500: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f  ristics method o
6510: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
6520: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62  o_methods].** ob
6530: 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ject returns an 
6540: 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
6550: 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65   a vector of the
6560: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73  se.** bit values
6570: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20   expressing I/O 
6580: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  characteristics 
6590: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72  of the mass stor
65a0: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  age.** device th
65b0: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c  at holds the fil
65c0: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  e that the [sqli
65d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
65e0: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a  ** refers to..**
65f0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
6600: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
6610: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
6620: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
6630: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
6640: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
6650: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
6660: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
6670: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
6680: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
6690: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
66a0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
66b0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
66c0: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
66d0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
66e0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
66f0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
6700: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
6710: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
6720: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
6730: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
6740: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
6750: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
6760: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
6770: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
6780: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
6790: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
67a0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
67b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
67c0: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
67d0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
67e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
67f0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
6800: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
6810: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
6820: 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20   xWrite().  The 
6830: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
6840: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
6850: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6860: 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65  that.** after re
6870: 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  boot following a
6880: 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20   crash or power 
6890: 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62  loss, the only b
68a0: 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c  ytes in a.** fil
68b0: 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74  e that were writ
68c0: 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69  ten at the appli
68d0: 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67  cation level mig
68e0: 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a  ht have changed.
68f0: 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61  ** and that adja
6900: 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e  cent bytes, even
6910: 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68   bytes within th
6920: 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72  e same sector ar
6930: 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20  e.** guaranteed 
6940: 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e  to be unchanged.
6950: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6960: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
6970: 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67  HEN_OPEN.** flag
6980: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 61   indicate that a
6990: 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
69a0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 65  deleted when ope
69b0: 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54  n.  The.** SQLIT
69c0: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
69d0: 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73  E flag indicates
69e0: 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 20 69   that the file i
69f0: 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c  s on.** read-onl
6a00: 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e 6e  y media and cann
6a10: 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 65 76  ot be changed ev
6a20: 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73 20  en by processes 
6a30: 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64  with.** elevated
6a40: 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a   privileges..*/.
6a50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6a60: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
6a70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6a80: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
6a90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6aa0: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
6ab0: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
6ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6ad0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
6ae0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6af0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
6b00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6b10: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6b20: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
6b30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6b40: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
6b50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6b60: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
6b70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
6b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6b90: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
6ba0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6bb0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
6bc0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
6bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6be0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
6bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6c00: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
6c10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6c20: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
6c30: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
6c40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6c50: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6c60: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6c70: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
6c80: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6c90: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
6ca0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
6cb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6cc0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
6cd0: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
6ce0: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
6cf0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6d00: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
6d10: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
6d20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6d30: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20  IMMUTABLE       
6d40: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
6d50: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
6d60: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20  F: File Locking 
6d70: 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  Levels.**.** SQL
6d80: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
6d90: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6da0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6db0: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
6dc0: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
6dd0: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
6de0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
6df0: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
6e00: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6e10: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
6e20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6e30: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
6e40: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
6e50: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
6e60: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
6e70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6e80: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
6e90: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
6ea0: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
6eb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6ec0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
6ed0: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
6ee0: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
6ef0: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a  ion Type Flags.*
6f00: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65  *.** When SQLite
6f10: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79   invokes the xSy
6f20: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61  nc() method of a
6f30: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
6f40: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6f50: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69   it uses a combi
6f60: 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  nation of.** the
6f70: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
6f80: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  s as the second 
6f90: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
6fa0: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  When the SQLITE_
6fb0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c  SYNC_DATAONLY fl
6fc0: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d  ag is used, it m
6fd0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  eans that the.**
6fe0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20   sync operation 
6ff0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c  only needs to fl
7000: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73  ush data to mass
7010: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65   storage.  Inode
7020: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
7030: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73  need not be flus
7040: 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65  hed. If the lowe
7050: 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74  r four bits of t
7060: 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c  he flag.** equal
7070: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7080: 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  MAL, that means 
7090: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73  to use normal fs
70a0: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e  ync() semantics.
70b0: 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72  .** If the lower
70c0: 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c   four bits equal
70d0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
70e0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  L, that means.**
70f0: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58   to use Mac OS X
7100: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
7110: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
7120: 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74  ()..**.** Do not
7130: 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c   confuse the SQL
7140: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7150: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7160: 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69  FULL flags.** wi
7170: 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73  th the [PRAGMA s
7180: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d  ynchronous]=NORM
7190: 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73  AL and [PRAGMA s
71a0: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c  ynchronous]=FULL
71b0: 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54  .** settings.  T
71c0: 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20  he [synchronous 
71d0: 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e  pragma] determin
71e0: 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f  es when calls to
71f0: 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46   the.** xSync VF
7200: 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61  S method occur a
7210: 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f  nd applies unifo
7220: 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  rmly across all 
7230: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68  platforms..** Th
7240: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7250: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7260: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20  SYNC_FULL flags 
7270: 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a  determine how.**
7280: 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69   energetic or ri
7290: 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66  gorous or forcef
72a0: 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72  ul the sync oper
72b0: 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a  ations are and.*
72c0: 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69  * only make a di
72d0: 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20  fference on Mac 
72e0: 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61  OSX for the defa
72f0: 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e  ult SQLite code.
7300: 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79  .** (Third-party
7310: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7320: 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  ions might also 
7330: 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
7340: 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
7350: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7360: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
7370: 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f  NC_FULL, but amo
7380: 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74  ng the.** operat
7390: 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69  ing systems nati
73a0: 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62  vely supported b
73b0: 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d  y SQLite, only M
73c0: 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20  ac OSX.** cares 
73d0: 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72  about the differ
73e0: 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e  ence.).*/.#defin
73f0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7400: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30  RMAL        0x00
7410: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
7420: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20  TE_SYNC_FULL    
7430: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64        0x00003.#d
7440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7450: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20  C_DATAONLY      
7460: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43  0x00010../*.** C
7470: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7480: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20  rface Open File 
7490: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20  Handle.**.** An 
74a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
74b0: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
74c0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e   an open file in
74d0: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
74e0: 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72  3_vfs | OS inter
74f0: 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e  face layer].  In
7500: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
7510: 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  rface.** impleme
7520: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a  ntations will.**
7530: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73   want to subclas
7540: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79  s this object by
7550: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74   appending addit
7560: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20  ional fields.** 
7570: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73  for their own us
7580: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73  e.  The pMethods
7590: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e   entry is a poin
75a0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
75b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
75c0: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
75d0: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f  fines methods fo
75e0: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20  r performing.** 
75f0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f  I/O operations o
7600: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  n the open file.
7610: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
7620: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
7630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74  sqlite3_file;.st
7640: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
7650: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75  e {.  const stru
7660: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
7670: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b  thods *pMethods;
7680: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
7690: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f   an open file */
76a0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
76b0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
76c0: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d  e File Virtual M
76d0: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a  ethods Object.**
76e0: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
76f0: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
7700: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7710: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65   method populate
7720: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s an.** [sqlite3
7730: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f  _file] object (o
7740: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79  r, more commonly
7750: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  , a subclass of 
7760: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
7770: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69  file] object) wi
7780: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  th a pointer to 
7790: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
77a0: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54  his object..** T
77b0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
77c0: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75  es the methods u
77d0: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  sed to perform v
77e0: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e  arious operation
77f0: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65  s.** against the
7800: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65   open file repre
7810: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73  sented by the [s
7820: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7830: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ect..**.** If th
7840: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7850: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74  Open] method set
7860: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  s the sqlite3_fi
7870: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
7880: 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e  ent .** to a non
7890: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
78a0: 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
78b0: 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73  io_methods.xClos
78c0: 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20  e method.** may 
78d0: 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20  be invoked even 
78e0: 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  if the [sqlite3_
78f0: 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72  vfs.xOpen] repor
7900: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c  ted that it fail
7910: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79  ed.  The.** only
7920: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20   way to prevent 
7930: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65  a call to xClose
7940: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
7950: 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  led [sqlite3_vfs
7960: 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f  .xOpen].** is fo
7970: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  r the [sqlite3_v
7980: 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74  fs.xOpen] to set
7990: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
79a0: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
79b0: 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  nt.** to NULL..*
79c0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
79d0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
79e0: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
79f0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7a00: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
7a10: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
7a20: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
7a30: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
7a40: 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ync()..** The se
7a50: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
7a60: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
7a70: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b  fullsync.  The [
7a80: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7a90: 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61  ONLY].** flag ma
7aa0: 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20  y be ORed in to 
7ab0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e  indicate that on
7ac0: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74  ly the data of t
7ad0: 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e  he file.** and n
7ae0: 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65  ot its inode nee
7af0: 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e  ds to be synced.
7b00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67  .**.** The integ
7b10: 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f  er values to xLo
7b20: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
7b30: 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a  () are one of.**
7b40: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7b50: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
7b60: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7b70: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
7b80: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7b90: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a  LOCK_RESERVED],.
7ba0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7bb0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
7bc0: 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
7bd0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7be0: 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78  ]..** </ul>.** x
7bf0: 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73  Lock() increases
7c00: 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f   the lock. xUnlo
7c10: 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74  ck() decreases t
7c20: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20  he lock..** The 
7c30: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
7c40: 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63  ck() method chec
7c50: 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64  ks whether any d
7c60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
7c70: 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e  on,.** either in
7c80: 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72   this process or
7c90: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70   in some other p
7ca0: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69  rocess, is holdi
7cb0: 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a  ng a RESERVED,.*
7cc0: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58  * PENDING, or EX
7cd0: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20  CLUSIVE lock on 
7ce0: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65  the file.  It re
7cf0: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66  turns true.** if
7d00: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69   such a lock exi
7d10: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74  sts and false ot
7d20: 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54  herwise..**.** T
7d30: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
7d40: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
7d50: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
7d60: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
7d70: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
7d80: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
7d90: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
7da0: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
7db0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
7dc0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
7dd0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
7de0: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
7df0: 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69  ument is an.** i
7e00: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
7e10: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
7e20: 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  nt is a generic 
7e30: 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64  pointer intended
7e40: 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20   to.** point to 
7e50: 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  a structure that
7e60: 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67   may contain arg
7e70: 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20  uments or space 
7e80: 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77  in which to.** w
7e90: 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75  rite return valu
7ea0: 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75  es.  Potential u
7eb0: 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e  ses for xFileCon
7ec0: 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a  trol() might be.
7ed0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20  ** functions to 
7ee0: 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20  enable blocking 
7ef0: 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f  locks with timeo
7f00: 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74  uts, to change t
7f10: 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74  he.** locking st
7f20: 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d  rategy (for exam
7f30: 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66  ple to use dot-f
7f40: 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69  ile locks), to i
7f50: 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20  nquire.** about 
7f60: 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20  the status of a 
7f70: 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61  lock, or to brea
7f80: 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20  k stale locks.  
7f90: 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f  The SQLite.** co
7fa0: 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20  re reserves all 
7fb0: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
7fc0: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
7fd0: 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c  n use..** A [fil
7fe0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
7ff0: 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  s | list of opco
8000: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
8010: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
8020: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
8030: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
8040: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
8050: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
8060: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
8070: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
8080: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
8090: 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d  cts.  VFS implem
80a0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
80b0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
80c0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72  TE_NOTFOUND] for
80d0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70   file control op
80e0: 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20  codes that they 
80f0: 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e  do not.** recogn
8100: 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ize..**.** The x
8110: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
8120: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
8130: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
8140: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
8150: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
8160: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
8170: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
8180: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
8190: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
81a0: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
81b0: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
81c0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
81d0: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
81e0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
81f0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
8200: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
8210: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
8220: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
8230: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
8240: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
8250: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8260: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
8270: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8280: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
8290: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
82a0: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
82b0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
82c0: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
82d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
82e0: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
82f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8300: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
8310: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8320: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
8330: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8340: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
8350: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8360: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
8370: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8380: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
8390: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
83a0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
83b0: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
83c0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
83d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
83e0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
83f0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
8400: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
8410: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
8420: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
8430: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
8440: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
8450: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
8460: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
8470: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
8480: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
8490: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
84a0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
84b0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
84c0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
84d0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
84e0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
84f0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
8500: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
8510: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
8520: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
8530: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
8540: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
8550: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
8560: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
8570: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
8580: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8590: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
85a0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
85b0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
85c0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
85d0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
85e0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
85f0: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
8600: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
8610: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
8620: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
8630: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
8640: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
8650: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
8660: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
8670: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
8680: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
8690: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
86a0: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
86b0: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
86c0: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
86d0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
86e0: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
86f0: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
8700: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
8710: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
8720: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8730: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
8740: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
8750: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
8760: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
8770: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
8780: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
8790: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
87a0: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
87b0: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
87c0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
87d0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
87e0: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
87f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
8800: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8810: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8820: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8830: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
8840: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8850: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
8860: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
8870: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8880: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
8890: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
88a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
88b0: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
88c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
88d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88e0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
88f0: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
8900: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8910: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
8920: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
8930: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
8940: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
8950: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
8960: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8970: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
8980: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
8990: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
89a0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
89b0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
89c0: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
89d0: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
89e0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
89f0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
8a00: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
8a10: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
8a20: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
8a30: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
8a40: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
8a50: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
8a60: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8a70: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
8a80: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
8a90: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
8aa0: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
8ab0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
8ac0: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
8ad0: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
8ae0: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
8af0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8b00: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
8b10: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74   */.  int (*xFet
8b20: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8b30: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8b40: 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74   iOfst, int iAmt
8b50: 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20  , void **pp);.  
8b60: 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28  int (*xUnfetch)(
8b70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8b80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8b90: 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20  st, void *p);.  
8ba0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8bb0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8bc0: 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a  ersion 3 */.  /*
8bd0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
8be0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
8bf0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
8c00: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
8c10: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
8c20: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
8c30: 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57   Opcodes.** KEYW
8c40: 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74  ORDS: {file cont
8c50: 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69  rol opcodes} {fi
8c60: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
8c70: 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  e}.**.** These i
8c80: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
8c90: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72   are opcodes for
8ca0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
8cb0: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  l method.** of t
8cc0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
8cd0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
8ce0: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  nd for the [sqli
8cf0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8d00: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
8d10: 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  ..**.** <ul>.** 
8d20: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8d30: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a  TL_LOCKSTATE]].*
8d40: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8d50: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f  NTL_LOCKSTATE] o
8d60: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
8d70: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
8d80: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
8d90: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
8da0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77  trol method to w
8db0: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74  rite the current
8dc0: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65   state of.** the
8dd0: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53   lock (one of [S
8de0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
8df0: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  , [SQLITE_LOCK_S
8e00: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  HARED],.** [SQLI
8e10: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
8e20: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8e30: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51  PENDING], or [SQ
8e40: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
8e50: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e  IVE]).** into an
8e60: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68   integer that th
8e70: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
8e80: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20  points to. This 
8e90: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
8ea0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
8eb0: 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79  ting and is only
8ec0: 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 20   available when 
8ed0: 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  the SQLITE_TEST.
8ee0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
8ef0: 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
8f00: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8f10: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
8f20: 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NT]].** The [SQL
8f30: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
8f40: 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  INT] opcode is u
8f50: 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f  sed by SQLite to
8f60: 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a   give the VFS.**
8f70: 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66   layer a hint of
8f80: 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64   how large the d
8f90: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
8fa0: 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72  l grow to be dur
8fb0: 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  ing the.** curre
8fc0: 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  nt transaction. 
8fd0: 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f   This hint is no
8fe0: 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  t guaranteed to 
8ff0: 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20  be accurate but 
9000: 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63  it.** is often c
9010: 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72  lose.  The under
9020: 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20  lying VFS might 
9030: 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c  choose to preall
9040: 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a  ocate database.*
9050: 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73  * file space bas
9060: 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ed on this hint 
9070: 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70  in order to help
9080: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64   writes to the d
9090: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
90a0: 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a  run faster..**.*
90b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
90c0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
90d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
90e0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
90f0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
9100: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
9110: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
9120: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
9130: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
9140: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
9150: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
9160: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
9170: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
9180: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
9190: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
91a0: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
91b0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
91c0: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
91d0: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
91e0: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
91f0: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
9200: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
9210: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
9220: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
9230: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
9240: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
9250: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
9260: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
9270: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
9280: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
9290: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
92a0: 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c  systems..**.** <
92b0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
92c0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d  L_FILE_POINTER]]
92d0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
92e0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
92f0: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ER] opcode is us
9300: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70  ed to obtain a p
9310: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
9320: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9330: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65  object associate
9340: 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  d with a particu
9350: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
9360: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
9370: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
9380: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
9390: 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  TER]..**.** <li>
93a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a  [[SQLITE_FCNTL_J
93b0: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d  OURNAL_POINTER]]
93c0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
93d0: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
93e0: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
93f0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
9400: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
9410: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9420: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
9430: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a 6f  ated with the jo
9440: 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 68  urnal file (eith
9450: 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62  er.** the [rollb
9460: 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20  ack journal] or 
9470: 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 64  the [write-ahead
9480: 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 72   log]) for a par
9490: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
94a0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
94b0: 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54   See also [SQLIT
94c0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
94d0: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  NTER]..**.** <li
94e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
94f0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
9500: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
9510: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
9520: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9530: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9540: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9550: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9560: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9570: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
9580: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
9590: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
95a0: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
95b0: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
95c0: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
95d0: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
95e0: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
95f0: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
9600: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
9610: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
9620: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9630: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9640: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9650: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
9660: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
9670: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
9680: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
9690: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
96a0: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
96b0: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
96c0: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
96d0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
96e0: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
96f0: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
9700: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
9710: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
9720: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
9730: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9740: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9750: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
9760: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
9770: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
9780: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
9790: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
97a0: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
97b0: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
97c0: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
97d0: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
97e0: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
97f0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
9800: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
9810: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9820: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9830: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9840: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
9850: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
9860: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
9870: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
9880: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
9890: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
98a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
98b0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
98c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
98d0: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
98e0: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
98f0: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9900: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
9910: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
9920: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
9930: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9940: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
9950: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
9960: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
9970: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
9980: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
9990: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
99a0: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
99b0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
99c0: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
99d0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
99e0: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
99f0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9a00: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9a10: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9a20: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
9a30: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9a40: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9a50: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
9a60: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9a70: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9a80: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9a90: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9aa0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9ab0: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9ac0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9ad0: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9ae0: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9af0: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9b00: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
9b10: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
9b20: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9b30: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9b40: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9b50: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
9b60: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
9b70: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
9b80: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
9b90: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9ba0: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9bb0: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9bc0: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9bd0: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9be0: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9bf0: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9c00: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
9c10: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
9c20: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9c30: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9c40: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9c50: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
9c60: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
9c70: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
9c80: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
9c90: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9ca0: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9cb0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9cc0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9cd0: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9ce0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9cf0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9d00: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9d10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9d20: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9d30: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9d40: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9d50: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
9d60: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
9d70: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
9d80: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
9d90: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9da0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9db0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9dc0: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9dd0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9de0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9df0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9e00: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9e10: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9e20: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9e30: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9e40: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9e50: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9e60: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9e70: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9e80: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9e90: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9ea0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9eb0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9ec0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9ed0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9ee0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9ef0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9f00: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9f10: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9f20: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9f30: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9f40: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9f50: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9f60: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9f70: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9f80: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9f90: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9fa0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9fb0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9fc0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9fd0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9fe0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9ff0: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
a000: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
a010: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
a020: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
a030: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
a040: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
a050: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
a060: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
a070: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
a080: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
a090: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
a0a0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
a0b0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
a0c0: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
a0d0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
a0e0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
a0f0: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
a100: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
a110: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
a120: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
a130: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
a140: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
a150: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
a160: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
a170: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
a180: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a190: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
a1a0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
a1b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
a1c0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
a1d0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
a1e0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
a1f0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
a200: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
a210: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
a220: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a230: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a240: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a250: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a260: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
a270: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
a280: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a290: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a2a0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a2b0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a2c0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a2d0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a2e0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a2f0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a300: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a310: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a320: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a330: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a340: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a350: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a360: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a370: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a380: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a390: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a3a0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a3b0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a3c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a3d0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a3e0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a3f0: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a400: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a410: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a420: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a430: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a440: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a450: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a460: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a470: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a480: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a490: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a4a0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a4b0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a4c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a4d0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a4e0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a4f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a500: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a510: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a520: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a530: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a540: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a550: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a560: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a570: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a580: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a590: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a5a0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a5b0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a5c0: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a5d0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a5e0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a5f0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a600: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a610: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a620: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a630: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a640: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a650: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a660: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a670: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a680: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a690: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a6a0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a6b0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a6c0: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a6d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a6e0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a6f0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a700: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a710: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a720: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a730: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a740: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a750: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a760: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a770: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a780: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a790: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a7a0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a7b0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a7c0: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a7d0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a7e0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a7f0: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a800: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a810: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a820: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a830: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a840: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a850: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a860: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a870: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a880: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a890: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a8a0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a8b0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a8c0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a8d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a8e0: 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e  S_POINTER]].** ^
a8f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a900: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f  L_VFS_POINTER] o
a910: 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f  pcode finds a po
a920: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
a930: 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73  -level.** [VFSes
a940: 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75  ] currently in u
a950: 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d  se.  ^(The argum
a960: 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69  ent X in.** sqli
a970: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a980: 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c  (db,SQLITE_FCNTL
a990: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20  _VFS_POINTER,X) 
a9a0: 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79  must be.** of ty
a9b0: 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73  pe "[sqlite3_vfs
a9c0: 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63  ] **".  This opc
a9d0: 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58  odes will set *X
a9e0: 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72  .** to a pointer
a9f0: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65   to the top-leve
aa00: 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65  l VFS.)^.** ^Whe
aa10: 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74  n there are mult
aa20: 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69  iple VFS shims i
aa30: 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69  n the stack, thi
aa40: 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74  s opcode finds t
aa50: 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74  he.** upper-most
aa60: 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a   shim only..**.*
aa70: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
aa80: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
aa90: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
aaa0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
aab0: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
aac0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
aad0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
aae0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
aaf0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
ab00: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
ab10: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
ab20: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
ab30: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
ab40: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
ab50: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
ab60: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
ab70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ab80: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
ab90: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
aba0: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
abb0: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
abc0: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
abd0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
abe0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
abf0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
ac00: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
ac10: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
ac20: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
ac30: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
ac40: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
ac50: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
ac60: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
ac70: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
ac80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
ac90: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
aca0: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
acb0: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
acc0: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
acd0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
ace0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
acf0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
ad00: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
ad10: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
ad20: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
ad30: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
ad40: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
ad50: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
ad60: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
ad70: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
ad80: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
ad90: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
ada0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
adb0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
adc0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
add0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
ade0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
adf0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
ae00: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
ae10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ae20: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
ae30: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
ae40: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
ae50: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
ae60: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
ae70: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
ae80: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
ae90: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
aea0: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
aeb0: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
aec0: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c  atement if resul
aed0: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c  t string is NULL
aee0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e  , or that return
aef0: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
af00: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  he result string
af10: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   if the string i
af20: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e  s non-NULL..** ^
af30: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
af40: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
af50: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
af60: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
af70: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
af80: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
af90: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
afa0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
afb0: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
afc0: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
afd0: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
afe0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
aff0: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
b000: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
b010: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
b020: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
b030: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b040: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
b050: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
b060: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
b070: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
b080: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
b090: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
b0a0: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
b0b0: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
b0c0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
b0d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b0e0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
b0f0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
b100: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b110: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
b120: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
b130: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
b140: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
b150: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
b160: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
b170: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
b180: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
b190: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
b1a0: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
b1b0: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
b1c0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
b1d0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
b1e0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
b1f0: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
b200: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
b210: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
b220: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
b230: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
b240: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
b250: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
b260: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
b270: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
b280: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
b290: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
b2a0: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
b2b0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
b2c0: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
b2d0: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
b2e0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
b2f0: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
b300: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
b310: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
b320: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
b330: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
b340: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
b350: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
b360: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
b370: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
b380: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
b390: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b3a0: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
b3b0: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
b3c0: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
b3d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b3e0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
b3f0: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
b400: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
b410: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
b420: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
b430: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
b440: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
b450: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
b460: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b470: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
b480: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
b490: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
b4a0: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
b4b0: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
b4c0: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
b4d0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b4e0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
b4f0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
b500: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
b510: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
b520: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
b530: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
b540: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
b550: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
b560: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
b570: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
b580: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b590: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
b5a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b5b0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
b5c0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b5d0: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
b5e0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
b5f0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
b600: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
b610: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
b620: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
b630: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
b640: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
b650: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
b660: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
b670: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
b680: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b690: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
b6a0: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
b6b0: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
b6c0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
b6d0: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
b6e0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
b6f0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
b700: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
b710: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
b720: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
b730: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
b740: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
b750: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
b760: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
b770: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
b780: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
b790: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
b7a0: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
b7b0: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
b7c0: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
b7d0: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
b7e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
b7f0: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
b800: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b810: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
b820: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
b830: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
b840: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
b850: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
b860: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
b870: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
b880: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
b890: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
b8a0: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
b8b0: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
b8c0: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
b8d0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
b8e0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
b8f0: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
b900: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
b910: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
b920: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
b930: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
b940: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
b950: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
b960: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
b970: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
b980: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
b990: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b9a0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
b9b0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b9c0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
b9d0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
b9e0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
b9f0: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
ba00: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
ba10: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
ba20: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
ba30: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
ba40: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
ba50: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
ba60: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
ba70: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
ba80: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
ba90: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
baa0: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
bab0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bac0: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
bad0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
bae0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
baf0: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
bb00: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
bb10: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
bb20: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
bb30: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
bb40: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
bb50: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
bb60: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
bb70: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
bb80: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
bb90: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
bba0: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
bbb0: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
bbc0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
bbd0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
bbe0: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
bbf0: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  efined..**.** <l
bc00: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bc10: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20  _WAL_BLOCK]].** 
bc20: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bc30: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20  L_WAL_BLOCK] is 
bc40: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
bc50: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69  VFS layer that i
bc60: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64  t might.** be ad
bc70: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c  vantageous to bl
bc80: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  ock on the next 
bc90: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20  WAL lock if the 
bca0: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65  lock is not imme
bcb0: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c  diately.** avail
bcc0: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73  able.  The WAL s
bcd0: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20  ubsystem issues 
bce0: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69  this signal duri
bcf0: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75  ng rare.** circu
bd00: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65  mstances in orde
bd10: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c  r to fix a probl
bd20: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79  em with priority
bd30: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41   inversion..** A
bd40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
bd50: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  ld <em>not</em> 
bd60: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  use this file-co
bd70: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ntrol..**.** <li
bd80: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bd90: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20  ZIPVFS]].** The 
bda0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
bdb0: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20  PVFS] opcode is 
bdc0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a  implemented by z
bdd0: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20  ipvfs only. All 
bde0: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f  other.** VFS sho
bdf0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
be00: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74  E_NOTFOUND for t
be10: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a  his opcode..**.*
be20: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
be30: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68  CNTL_RBU]].** Th
be40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
be50: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  RBU] opcode is i
be60: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
be70: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73  e special VFS us
be80: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55  ed by.** the RBU
be90: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e   extension only.
bea0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20    All other VFS 
beb0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
bec0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
bed0: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65  r.** this opcode
bee0: 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .  .** </ul>.*/.
bef0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bf00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
bf10: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
bf20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bf30: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
bf40: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
bf50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bf60: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
bf70: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
bf80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bf90: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
bfa0: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
bfb0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bfc0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
bfd0: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
bfe0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bff0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
c000: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
c010: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
c020: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
c030: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
c040: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
c050: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
c060: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
c070: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c080: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
c090: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
c0a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
c0b0: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
c0c0: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
c0d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
c0e0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
c0f0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
c100: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
c110: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
c120: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
c130: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
c140: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
c150: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
c160: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
c170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
c180: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
c190: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
c1a0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
c1b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c1c0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
c1d0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
c1e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c1f0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
c200: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
c210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c220: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
c230: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
c240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c250: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
c260: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
c270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c280: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
c290: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
c2a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c2b0: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
c2c0: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69          22.#defi
c2d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c2e0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
c2f0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e         23.#defin
c300: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
c310: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20  AL_BLOCK        
c320: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65        24.#define
c330: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49   SQLITE_FCNTL_ZI
c340: 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20  PVFS            
c350: 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20       25.#define 
c360: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
c370: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c380: 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53      26.#define S
c390: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
c3a0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
c3b0: 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51     27.#define SQ
c3c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
c3d0: 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  AL_POINTER      
c3e0: 20 20 32 38 0a 0a 2f 2a 20 64 65 70 72 65 63 61    28../* depreca
c3f0: 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65  ted names */.#de
c400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
c410: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c420: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
c430: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
c440: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
c450: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
c460: 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46  LE      SQLITE_F
c470: 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_SET_LOCKPRO
c480: 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53  XYFILE.#define S
c490: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
c4a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c               SQL
c4b0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45  ITE_FCNTL_LAST_E
c4c0: 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  RRNO.../*.** CAP
c4d0: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e  I3REF: Mutex Han
c4e0: 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  dle.**.** The mu
c4f0: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
c500: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
c510: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
c520: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
c530: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
c540: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
c550: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
c560: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
c570: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
c580: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
c590: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
c5a0: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
c5b0: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
c5c0: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
c5d0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
c5e0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
c5f0: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
c600: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
c610: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
c620: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
c630: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
c640: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
c650: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
c660: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
c670: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
c680: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
c690: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
c6a0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
c6b0: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
c6c0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
c6d0: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
c6e0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
c6f0: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
c700: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
c710: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
c720: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
c730: 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65  ile system".  Se
c740: 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20  e.** the [VFS | 
c750: 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  VFS documentatio
c760: 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69  n] for further i
c770: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
c780: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
c790: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
c7a0: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
c7b0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
c7c0: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
c7d0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
c7e0: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
c7f0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
c800: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
c810: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
c820: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
c830: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
c840: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
c850: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
c860: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
c870: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
c880: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
c890: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
c8a0: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
c8b0: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
c8c0: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
c8d0: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
c8e0: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
c8f0: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
c900: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
c910: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
c920: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
c930: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
c940: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
c950: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
c960: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
c970: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
c980: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
c990: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
c9a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
c9b0: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
c9c0: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
c9d0: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
c9e0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
c9f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
ca00: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
ca10: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
ca20: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
ca30: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
ca40: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
ca50: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
ca60: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
ca70: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
ca80: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
ca90: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
caa0: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
cab0: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
cac0: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
cad0: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
cae0: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
caf0: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
cb00: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
cb10: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
cb20: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
cb30: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
cb40: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
cb50: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
cb60: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
cb70: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
cb80: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
cb90: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
cba0: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
cbb0: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
cbc0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
cbd0: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
cbe0: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
cbf0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
cc00: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
cc10: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
cc20: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
cc30: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
cc40: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
cc50: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
cc60: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
cc70: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
cc80: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
cc90: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  modules..**.** [
cca0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
ccb0: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  en]].** ^SQLite 
ccc0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
ccd0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
cce0: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
ccf0: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
cd00: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
cd10: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
cd20: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
cd30: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20  hname() with an 
cd40: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20  optional suffix 
cd50: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20  added..** ^If a 
cd60: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20  suffix is added 
cd70: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  to the zFilename
cd80: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77   parameter, it w
cd90: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f  ill.** consist o
cda0: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63  f a single "-" c
cdb0: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65  haracter followe
cdc0: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61  d by no more tha
cdd0: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d  n.** 11 alphanum
cde0: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20  eric and/or "-" 
cdf0: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e  characters..** ^
ce00: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
ce10: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
ce20: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
ce30: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
ce40: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
ce50: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
ce60: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
ce70: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
ce80: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
ce90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
cea0: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
ceb0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
cec0: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
ced0: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
cee0: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
cef0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
cf00: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
cf10: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
cf20: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  to xOpen is a NU
cf30: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
cf40: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
cf50: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
cf60: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
cf70: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e  the file.  ^When
cf80: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69  ever the .** xFi
cf90: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
cfa0: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c   is NULL it will
cfb0: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73   also be the cas
cfc0: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c  e that the.** fl
cfd0: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69  ags parameter wi
cfe0: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ll include [SQLI
cff0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d000: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  CLOSE]..**.** Th
d010: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d020: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
d030: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
d040: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
d050: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
d060: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
d070: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
d080: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
d090: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
d0a0: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
d0b0: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
d0c0: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
d0d0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
d0e0: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
d0f0: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a  PEN_CREATE]. .**
d100: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
d110: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
d120: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
d130: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
d140: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
d150: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
d160: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
d170: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
d180: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53  e set..**.** ^(S
d190: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
d1a0: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
d1b0: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
d1c0: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
d1d0: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
d1e0: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
d1f0: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
d200: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
d210: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
d220: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
d230: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
d240: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
d250: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d260: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
d270: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d280: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
d290: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d2a0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
d2b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d2c0: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
d2d0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d2e0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
d2f0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
d300: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d310: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  WAL].** </ul>)^.
d320: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
d330: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
d340: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
d350: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
d360: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
d370: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
d380: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
d390: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
d3a0: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
d3b0: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
d3c0: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
d3d0: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
d3e0: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
d3f0: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
d400: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
d410: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
d420: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
d430: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
d440: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
d450: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
d460: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
d470: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
d480: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
d490: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
d4a0: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
d4b0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
d4c0: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
d4d0: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
d4e0: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
d4f0: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
d500: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
d510: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
d520: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
d530: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
d540: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
d550: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
d560: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
d570: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
d580: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
d590: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
d5a0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
d5b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
d5c0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
d5d0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
d5e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
d5f0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
d600: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
d610: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
d620: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
d630: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20  s closed.  ^The 
d640: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
d650: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77  ETEONCLOSE].** w
d660: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54  ill be set for T
d670: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e  EMP databases an
d680: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73  d their journals
d690: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64  , transient.** d
d6a0: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75  atabases, and su
d6b0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
d6c0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
d6d0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
d6e0: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  ag is always use
d6f0: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e  d in conjunction
d700: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
d710: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d720: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72  ] flag, which ar
d730: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a  e both directly.
d740: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20  ** analogous to 
d750: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f  the O_EXCL and O
d760: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20  _CREAT flags of 
d770: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29  the POSIX open()
d780: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51  .** API.  The SQ
d790: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
d7a0: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70  IVE flag, when p
d7b0: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a  aired with the .
d7c0: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ** SQLITE_OPEN_C
d7d0: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74  REATE, is used t
d7e0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
d7f0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61  file should alwa
d800: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64  ys.** be created
d810: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73  , and that it is
d820: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20   an error if it 
d830: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a  already exists..
d840: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c  ** It is <i>not<
d850: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69  /i> used to indi
d860: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68  cate the file sh
d870: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a  ould be opened .
d880: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
d890: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e   access..**.** ^
d8a0: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
d8b0: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
d8c0: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
d8d0: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
d8e0: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
d8f0: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
d900: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
d910: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
d920: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
d930: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
d940: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
d950: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
d960: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
d970: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
d980: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
d990: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
d9a0: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
d9b0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
d9c0: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
d9d0: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
d9e0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
d9f0: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
da00: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
da10: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
da20: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
da30: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
da40: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
da50: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
da60: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
da70: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
da80: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
da90: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
daa0: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
dab0: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
dac0: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
dad0: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
dae0: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65  Access]].** ^The
daf0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
db00: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
db10: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
db20: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
db30: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
db40: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
db50: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
db60: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
db70: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
db80: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
db90: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
dba0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
dbb0: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
dbc0: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
dbd0: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
dbe0: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
dbf0: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
dc00: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
dc10: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
dc20: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
dc30: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
dc40: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
dc50: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
dc60: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
dc70: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20  ame.  The exact 
dc80: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
dc90: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
dca0: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
dcb0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
dcc0: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  th  methods. If 
dcd0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
dce0: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
dcf0: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
dd00: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
dd10: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
dd20: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
dd30: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
dd40: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
dd50: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
dd60: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
dd70: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
dd80: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
dd90: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
dda0: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
ddb0: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
ddc0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
ddd0: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
dde0: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65  (), xCurrentTime
ddf0: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
de00: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69  TimeInt64().** i
de10: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
de20: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
de30: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
de40: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
de50: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
de60: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
de70: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
de80: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
de90: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
dea0: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
deb0: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
dec0: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
ded0: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
dee0: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
def0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
df00: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
df10: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
df20: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
df30: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
df40: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
df50: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
df60: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
df70: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
df80: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
df90: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
dfa0: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e  n.  ^The xCurren
dfb0: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
dfc0: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
dfd0: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
dfe0: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
dff0: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a  te and time as.*
e000: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  * a floating poi
e010: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68  nt value..** ^Th
e020: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
e030: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74  t64() method ret
e040: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65  urns, as an inte
e050: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a  ger, the Julian.
e060: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75  ** Day Number mu
e070: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30  ltiplied by 8640
e080: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72  0000 (the number
e090: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
e0a0: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75   in .** a 24-hou
e0b0: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51  r day).  .** ^SQ
e0c0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
e0d0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
e0e0: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20  t64() method to 
e0f0: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a  get the current.
e100: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
e110: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20   if that method 
e120: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66  is available (if
e130: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f   iVersion is 2 o
e140: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e  r .** greater an
e150: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  d the function p
e160: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
e170: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c  LL) and will fal
e180: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75  l back.** to xCu
e190: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78  rrentTime() if x
e1a0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
e1b0: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  () is unavailabl
e1c0: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53  e..**.** ^The xS
e1d0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
e1e0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xGetSystemCall()
e1f0: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65  , and xNestSyste
e200: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  mCall() interfac
e210: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73  es.** are not us
e220: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65  ed by the SQLite
e230: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70   core.  These op
e240: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65  tional interface
e250: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a  s are provided.*
e260: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20  * by some VFSes 
e270: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65  to facilitate te
e280: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53  sting of the VFS
e290: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69   code. By overri
e2a0: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20  ding .** system 
e2b0: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74  calls with funct
e2c0: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63  ions under its c
e2d0: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70  ontrol, a test p
e2e0: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69  rogram can.** si
e2f0: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e  mulate faults an
e300: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  d error conditio
e310: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74  ns that would ot
e320: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69  herwise be diffi
e330: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73  cult.** or impos
e340: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e  sible to induce.
e350: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73    The set of sys
e360: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63  tem calls that c
e370: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
e380: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20  .** varies from 
e390: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68  one VFS to anoth
e3a0: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65  er, and from one
e3b0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
e3c0: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a  same VFS to the.
e3d0: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
e3e0: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
e3f0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
e400: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65   must be prepare
e410: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20  d for any.** or 
e420: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74  all of these int
e430: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55  erfaces to be NU
e440: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20  LL or for their 
e450: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e  behavior to chan
e460: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72  ge.** from one r
e470: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
e480: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
e490: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d  s must not attem
e4a0: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20  pt to access.** 
e4b0: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74  any of these met
e4c0: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72  hods if the iVer
e4d0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20  sion of the VFS 
e4e0: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a  is less than 3..
e4f0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
e500: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
e510: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64  lite3_vfs;.typed
e520: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
e530: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76  3_syscall_ptr)(v
e540: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c  oid);.struct sql
e550: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
e560: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
e570: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
e580: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
e590: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20  r (currently 3) 
e5a0: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
e5b0: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
e5c0: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
e5d0: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
e5e0: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
e5f0: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
e600: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
e610: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
e620: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
e630: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
e640: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
e650: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
e660: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
e670: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
e680: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
e690: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
e6a0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
e6b0: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
e6c0: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
e6d0: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
e6e0: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
e6f0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e700: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
e710: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
e720: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
e730: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
e740: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
e750: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
e760: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e770: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
e780: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
e790: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
e7a0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e7b0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
e7c0: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
e7d0: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
e7e0: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
e7f0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e800: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
e810: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
e820: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
e830: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
e840: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e850: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
e860: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
e870: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
e880: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
e890: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
e8a0: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
e8b0: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
e8c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
e8d0: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
e8e0: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
e8f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
e900: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
e910: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
e920: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
e930: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
e940: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
e950: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
e960: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
e970: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
e980: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
e990: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
e9a0: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
e9b0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
e9c0: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
e9d0: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
e9e0: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
e9f0: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20  re in version 1 
ea00: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
ea10: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65  s object.  ** de
ea20: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65  finition.  Those
ea30: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65   that follow are
ea40: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f   added in versio
ea50: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a  n 2 or later.  *
ea60: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  /.  int (*xCurre
ea70: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
ea80: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
ea90: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
eaa0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
eab0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
eac0: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
ead0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
eae0: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54  s object..  ** T
eaf0: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66  hose below are f
eb00: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64  or version 3 and
eb10: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20   greater..  */. 
eb20: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65   int (*xSetSyste
eb30: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
eb40: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
eb50: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
eb60: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20  syscall_ptr);.  
eb70: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
eb80: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d  ptr (*xGetSystem
eb90: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
eba0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ebb0: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20  zName);.  const 
ebc0: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73  char *(*xNextSys
ebd0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
ebe0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ebf0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a  r *zName);.  /*.
ec00: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
ec10: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
ec20: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68  rsions 1 through
ec30: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   3 of the sqlite
ec40: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
ec50: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
ec60: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
ec70: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  future versions.
ec80: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
ec90: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
eca0: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
ecb0: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
ecc0: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
ecd0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
ece0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
ecf0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
ed00: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
ed10: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
ed20: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
ed30: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
ed40: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
ed50: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
ed60: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
ed70: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
ed80: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
ed90: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
eda0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
edb0: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
edc0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
edd0: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
ede0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
edf0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
ee00: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
ee10: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
ee20: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
ee30: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
ee40: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
ee50: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
ee60: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
ee70: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
ee80: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
ee90: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
eea0: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
eeb0: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
eec0: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
eed0: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
eee0: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
eef0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
ef00: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
ef10: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
ef20: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
ef30: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
ef40: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
ef50: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
ef60: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
ef70: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
ef80: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
ef90: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
efa0: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
efb0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
efc0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
efd0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
efe0: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
eff0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
f000: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
f010: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
f020: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
f030: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
f040: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
f050: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
f060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
f070: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
f080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f090: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
f0a0: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
f0b0: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
f0c0: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
f0d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
f0e0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
f0f0: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
f100: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
f110: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
f120: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
f130: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
f140: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
f150: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
f160: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
f170: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
f180: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
f190: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
f1a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
f1b0: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
f1c0: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
f1d0: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
f1e0: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
f1f0: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
f200: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
f210: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
f220: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
f230: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
f240: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f250: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
f260: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
f270: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f280: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
f290: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
f2a0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
f2b0: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
f2c0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
f2d0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
f2e0: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
f2f0: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
f300: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
f310: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
f320: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
f330: 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f   on the correspo
f340: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
f350: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f360: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
f370: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
f380: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
f390: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
f3a0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
f3b0: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
f3c0: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
f3d0: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
f3e0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
f3f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f400: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
f410: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
f420: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
f430: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
f440: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
f450: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
f460: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
f470: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
f480: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
f490: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
f4a0: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
f4b0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
f4c0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f4d0: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
f4e0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
f4f0: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
f500: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
f510: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
f520: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
f530: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
f540: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
f550: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
f560: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
f570: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
f580: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f590: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
f5a0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
f5b0: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
f5c0: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
f5d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
f5e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f5f0: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
f600: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
f610: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
f620: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
f630: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
f640: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
f650: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
f660: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
f670: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f680: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
f690: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
f6a0: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
f6b0: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
f6c0: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
f6d0: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
f6e0: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
f6f0: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
f700: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
f710: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
f720: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
f730: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
f740: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
f750: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
f760: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f770: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
f780: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
f790: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
f7a0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
f7b0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
f7c0: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
f7d0: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
f7e0: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
f7f0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
f800: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
f810: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
f820: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
f830: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
f840: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f850: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
f860: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
f870: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
f880: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
f890: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
f8a0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
f8b0: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
f8c0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
f8d0: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
f8e0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
f8f0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
f900: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
f910: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
f920: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
f930: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
f940: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
f950: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
f960: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
f970: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
f980: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
f990: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
f9a0: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
f9b0: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
f9c0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
f9d0: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
f9e0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
f9f0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fa00: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fa10: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
fa20: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
fa30: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
fa40: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
fa50: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fa60: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
fa70: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
fa80: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
fa90: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
faa0: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
fab0: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
fac0: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
fad0: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
fae0: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
faf0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
fb00: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
fb10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
fb20: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
fb30: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
fb40: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
fb50: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
fb60: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
fb70: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
fb80: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
fb90: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
fba0: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
fbb0: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
fbc0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
fbd0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
fbe0: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
fbf0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
fc00: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
fc10: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
fc20: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fc30: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
fc40: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
fc50: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
fc60: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
fc70: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
fc80: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
fc90: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
fca0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
fcb0: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
fcc0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
fcd0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
fce0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fcf0: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
fd00: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
fd10: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
fd20: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
fd30: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
fd40: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
fd50: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
fd60: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
fd70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fd80: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
fd90: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
fda0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
fdb0: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
fdc0: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
fdd0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
fde0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
fdf0: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
fe00: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
fe10: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
fe20: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
fe30: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
fe40: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
fe50: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
fe60: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
fe70: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
fe80: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
fe90: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
fea0: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
feb0: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
fec0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fed0: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
fee0: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
fef0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
ff00: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
ff10: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
ff20: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
ff30: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
ff40: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
ff50: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
ff60: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
ff70: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
ff80: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
ff90: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
ffa0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ffb0: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
ffc0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
ffd0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
ffe0: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
fff0: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
10000 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
10010 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
10020 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
10030 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
10040 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
10050 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10060 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
10070 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
10080 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
10090 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
100a0 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
100b0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
100c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
100d0 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
100e0 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
100f0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
10100 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
10110 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
10120 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
10130 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10140 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
10150 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
10160 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
10170 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
10180 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
10190 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
101a0 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
101b0 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
101c0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
101d0 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
101e0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
101f0 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
10200 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
10210 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
10220 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
10230 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
10240 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
10250 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
10260 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10270 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
10280 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
10290 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
102a0 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
102b0 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
102c0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
102d0 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
102e0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
102f0 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
10300 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10310 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
10320 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
10330 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10340 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
10350 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
10360 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
10370 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
10380 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
10390 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
103a0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
103b0 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
103c0 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
103d0 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
103e0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
103f0 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
10400 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
10410 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
10420 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
10430 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
10440 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
10450 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
10460 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
10470 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
10480 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
10490 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
104a0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
104b0 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
104c0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
104d0 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
104e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
104f0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
10500 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
10510 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
10520 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
10530 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
10540 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
10550 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
10560 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
10570 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
10580 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
10590 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
105a0 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
105b0 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
105c0 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lure..*/.SQLITE_
105d0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
105e0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 69  TDCALL sqlite3_i
105f0 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
10600 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
10610 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
10620 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10630 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
10640 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
10650 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 73 5f  CALL sqlite3_os_
10660 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49  init(void);.SQLI
10670 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
10680 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
10690 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
106a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
106b0 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
106c0 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
106d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
106e0 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
106f0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
10700 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
10710 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
10720 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
10730 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
10740 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
10750 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
10760 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
10770 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
10780 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
10790 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
107a0 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
107b0 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
107c0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
107d0 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
107e0 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
107f0 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
10800 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
10810 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
10820 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c  l needs..**.** <
10830 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  b>The sqlite3_co
10840 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10850 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
10860 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74  fe. The applicat
10870 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75  ion.** must ensu
10880 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
10890 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
108a0 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
108b0 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
108c0 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
108d0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
108e0 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20  ning.</b>.**.** 
108f0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10900 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ig() interface.*
10910 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
10920 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
10930 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
10940 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
10950 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10960 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
10970 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
10980 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
10990 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
109a0 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
109b0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
109c0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
109d0 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
109e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
109f0 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
10a00 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
10a10 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
10a20 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
10a30 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
10a40 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
10a50 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
10a60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
10a70 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
10a80 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
10a90 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
10aa0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
10ab0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
10ac0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
10ad0 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
10ae0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10af0 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
10b00 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
10b10 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
10b20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
10b30 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
10b40 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
10b50 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
10b60 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
10b70 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
10b80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10b90 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
10ba0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10bb0 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
10bc0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
10bd0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
10be0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
10bf0 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
10c00 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
10c10 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
10c20 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
10c30 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
10c40 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
10c50 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53  rror code]..*/.S
10c60 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
10c70 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74  LITE_CDECL sqlit
10c80 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
10c90 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
10ca0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
10cb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10cc0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
10cd0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
10ce0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
10cf0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
10d00 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
10d10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
10d20 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
10d30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10d40 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
10d50 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
10d60 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10d70 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
10d80 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
10d90 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
10da0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
10db0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
10dc0 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
10dd0 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
10de0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
10df0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
10e00 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
10e10 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
10e20 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
10e30 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
10e40 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
10e50 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
10e60 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
10e70 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
10e80 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
10e90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10ea0 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
10eb0 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
10ec0 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
10ed0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
10ee0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
10ef0 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
10f00 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
10f10 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
10f20 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
10f30 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
10f40 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
10f50 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
10f60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
10f70 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 20  nt SQLITE_CDECL 
10f80 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10f90 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
10fa0 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
10fb0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
10fc0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
10fd0 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  tines.**.** An i
10fe0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
10ff0 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
11000 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
11010 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
11020 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
11030 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11040 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
11050 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
11060 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
11070 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
11080 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
11090 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
110a0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
110b0 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
110c0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
110d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
110e0 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
110f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11100 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
11110 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20  NFIG_MALLOC] or 
11120 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
11130 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20  ETMALLOC].  .** 
11140 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
11150 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
11160 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
11170 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
11180 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
11190 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
111a0 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63  OC]).** during c
111b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
111c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
111d0 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
111e0 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
111f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
11200 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74  system for SQLit
11210 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
11220 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d   of its.** dynam
11230 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
11240 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
11250 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
11260 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c  th several [buil
11270 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
11280 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20  cators].** that 
11290 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64  are perfectly ad
112a0 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
112b0 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
112c0 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
112d0 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
112e0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
112f0 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
11300 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
11310 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
11320 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
11330 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
11340 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
11350 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
11360 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
11370 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
11380 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
11390 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
113a0 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
113b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
113c0 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
113d0 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
113e0 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
113f0 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
11400 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
11410 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
11420 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
11430 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
11440 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c  .** The xMalloc,
11450 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78   xRealloc, and x
11460 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
11470 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
11480 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  ** malloc(), rea
11490 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
114a0 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
114b0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
114c0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c  library..** ^SQL
114d0 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
114e0 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61  hat the second a
114f0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52  rgument to.** xR
11500 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73  ealloc is always
11510 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65   a value returne
11520 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c  d by a prior cal
11530 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a  l to xRoundup..*
11540 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
11550 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
11560 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
11570 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11580 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
11590 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
115a0 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
115b0 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
115c0 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
115d0 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
115e0 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
115f0 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
11600 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
11610 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
11620 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
11630 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
11640 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
11650 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
11660 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
11670 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
11680 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
11690 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
116a0 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
116b0 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
116c0 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
116d0 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
116e0 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
116f0 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
11700 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
11710 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
11720 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
11730 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
11740 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
11750 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
11760 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
11770 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
11780 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
11790 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
117a0 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
117b0 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
117c0 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
117d0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
117e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
117f0 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
11800 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
11810 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
11820 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11830 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tor.  For exampl
11840 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
11850 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
11860 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
11870 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
11880 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
11890 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
118a0 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
118b0 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
118c0 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
118d0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
118e0 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
118f0 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
11900 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
11910 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
11920 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
11930 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
11940 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
11950 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
11960 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
11970 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
11980 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
11990 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
119a0 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
119b0 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
119c0 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
119d0 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
119e0 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
119f0 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
11a00 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
11a10 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
11a20 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
11a30 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
11a40 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
11a50 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
11a60 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
11a70 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
11a80 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
11a90 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
11aa0 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
11ab0 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
11ac0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
11ad0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
11ae0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11af0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
11b00 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
11b10 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
11b20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
11b30 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
11b40 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
11b50 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
11b60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
11b70 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
11b80 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
11b90 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
11ba0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
11bb0 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
11bc0 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
11bd0 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
11be0 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
11bf0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
11c00 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
11c10 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
11c20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
11c30 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
11c40 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
11c50 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
11c60 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11c70 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
11c80 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
11c90 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11ca0 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
11cb0 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
11cc0 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
11cd0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
11ce0 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
11cf0 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
11d00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
11d10 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
11d20 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
11d30 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
11d40 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
11d50 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
11d60 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
11d70 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
11d80 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
11d90 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
11da0 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
11db0 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
11dc0 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
11dd0 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
11de0 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
11df0 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
11e00 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
11e10 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
11e20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
11e30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
11e40 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
11e50 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
11e60 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
11e70 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
11e80 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
11e90 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
11ea0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
11eb0 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
11ec0 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
11ed0 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
11ee0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11ef0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
11f00 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
11f10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11f20 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
11f30 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
11f40 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
11f50 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
11f60 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
11f70 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
11f80 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
11f90 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
11fa0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11fb0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
11fc0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
11fd0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
11fe0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
11ff0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
12000 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
12010 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
12020 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
12030 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
12040 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
12050 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
12060 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
12070 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
12080 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
12090 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
120a0 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
120b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
120c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
120d0 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
120e0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
120f0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
12100 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
12110 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
12120 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
12130 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
12140 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
12150 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
12160 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
12170 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
12180 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
12190 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
121a0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
121b0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
121c0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
121d0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
121e0 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
121f0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
12200 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
12210 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
12220 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
12230 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
12240 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
12250 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
12260 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
12270 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
12280 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
12290 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
122a0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
122b0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
122c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
122d0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
122e0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
122f0 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
12300 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
12310 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
12320 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
12330 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
12340 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12350 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
12360 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
12370 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
12380 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
12390 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
123a0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
123b0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
123c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
123d0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
123e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
123f0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
12400 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
12410 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
12420 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12430 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
12440 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12450 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12460 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
12470 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
12480 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
12490 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
124a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
124b0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
124c0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
124d0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
124e0 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
124f0 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
12500 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
12510 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12520 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
12530 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
12540 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
12550 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
12560 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
12570 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
12580 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
12590 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
125a0 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
125b0 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
125c0 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
125d0 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
125e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
125f0 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
12600 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
12610 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12620 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
12630 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
12640 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
12650 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
12660 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
12670 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
12680 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
12690 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
126a0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
126b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
126c0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
126d0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
126e0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
126f0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
12700 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
12710 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
12720 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
12730 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12740 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
12750 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12760 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
12770 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
12780 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
12790 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
127a0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
127b0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
127c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
127d0 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
127e0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
127f0 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
12800 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
12810 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
12820 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
12830 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
12840 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
12850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12860 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
12870 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
12880 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
12890 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
128a0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
128b0 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
128c0 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
128d0 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
128e0 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
128f0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
12900 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12910 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
12920 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
12930 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
12940 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
12950 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
12960 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
12970 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
12980 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
12990 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
129a0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
129b0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
129c0 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
129d0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
129e0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
129f0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
12a00 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12a10 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
12a20 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
12a30 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
12a40 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
12a50 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
12a60 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
12a70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12a80 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
12a90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
12aa0 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
12ab0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
12ac0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
12ad0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12ae0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
12af0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12b00 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
12b10 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12b20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12b30 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12b40 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  G_MALLOC option 
12b50 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12b60 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
12b70 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
12b80 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
12b90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
12ba0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
12bb0 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
12bc0 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
12bd0 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
12be0 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
12bf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12c00 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
12c10 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
12c20 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12c30 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
12c40 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
12c50 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
12c60 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
12c70 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
12c80 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
12c90 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12ca0 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
12cb0 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
12cc0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
12cd0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
12ce0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12cf0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
12d00 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
12d10 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
12d20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
12d30 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12d40 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  _GETMALLOC optio
12d50 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
12d60 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
12d70 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
12d80 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
12d90 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12da0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12db0 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73  cture..** The [s
12dc0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12dd0 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
12de0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
12df0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
12e00 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
12e10 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12e20 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
12e30 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
12e40 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
12e50 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
12e60 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
12e70 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
12e80 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
12e90 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
12ea0 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
12eb0 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
12ec0 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
12ed0 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
12ee0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12ef0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
12f00 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12f10 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
12f20 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
12f30 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
12f40 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65  ATUS option take
12f50 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
12f60 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a  t of type int,.*
12f70 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  * interpreted as
12f80 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63   a boolean, whic
12f90 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
12fa0 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
12fb0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72  tion of.** memor
12fc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
12fd0 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
12fe0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12ff0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
13000 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68  .** disabled, th
13010 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  e following SQLi
13020 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
13030 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
13040 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
13050 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
13060 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
13070 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
13080 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
13090 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
130a0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
130b0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
130c0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
130d0 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a  te3_status64()].
130e0 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
130f0 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
13100 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
13110 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
13120 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
13130 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
13140 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
13150 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
13160 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
13170 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
13180 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
13190 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
131a0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
131b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
131c0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
131d0 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
131e0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
131f0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
13200 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13210 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65  RATCH option spe
13220 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
13230 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a  memory buffer.**
13240 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
13250 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63 68   use for scratch
13260 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72   memory.  ^(Ther
13270 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
13280 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49  ments.** to SQLI
13290 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
132a0 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  H:  A pointer an
132b0 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
132c0 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
132d0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
132e0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
132f0 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  ons will be.** d
13300 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f  rawn, the size o
13310 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61  f each scratch a
13320 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a  llocation (sz),.
13330 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ** and the maxim
13340 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72  um number of scr
13350 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
13360 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66   (N).)^.** The f
13370 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
13380 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
13390 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
133a0 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
133b0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
133c0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
133d0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
133e0 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68   not use more th
133f0 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62  an one scratch b
13400 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61  uffers per threa
13410 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  d..** ^SQLite wi
13420 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73 74  ll never request
13430 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
13440 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
13450 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
13460 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
13470 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   size..** ^If SQ
13480 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
13490 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73   additional.** s
134a0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
134b0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
134c0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f  vided by this co
134d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
134e0 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71  on, then .** [sq
134f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13500 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20  will be used to 
13510 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
13520 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20  y needed.<p>.** 
13530 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63  ^When the applic
13540 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61  ation provides a
13550 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72  ny amount of scr
13560 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e  atch memory usin
13570 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  g.** SQLITE_CONF
13580 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69  IG_SCRATCH, SQLi
13590 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65  te avoids unnece
135a0 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b  ssary large.** [
135b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68  sqlite3_malloc|h
135c0 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d  eap allocations]
135d0 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65  ..** This can he
135e0 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66  lp [Robson proof
135f0 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20  |prevent memory 
13600 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
13610 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70  res] due to heap
13620 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  .** fragmentatio
13630 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20  n in low-memory 
13640 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
13650 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
13660 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13670 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
13680 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
13690 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
136a0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
136b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
136c0 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  HE option specif
136d0 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f  ies a memory poo
136e0 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  l.** that SQLite
136f0 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65   can use for the
13700 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
13710 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
13720 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61  fault page.** ca
13730 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
13740 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
13750 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13760 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66  on is a no-op if
13770 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
13780 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
13790 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
137a0 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
137b0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
137c0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e  CONFIG_PCACHE2].
137d0 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
137e0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
137f0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
13800 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69  PAGECACHE: A poi
13810 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74  nter to.** 8-byt
13820 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  e aligned memory
13830 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a   (pMem), the siz
13840 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 63  e of each page c
13850 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a  ache line (sz),.
13860 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ** and the numbe
13870 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73  r of cache lines
13880 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
13890 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
138a0 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
138b0 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
138c0 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
138d0 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
138e0 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33  een 512 and 6553
138f0 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74  6) plus some ext
13900 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63  ra bytes for eac
13910 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
13920 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  .  ^The number o
13930 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65  f extra bytes ne
13940 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65  eded by the page
13950 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62   header.** can b
13960 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
13970 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ng [SQLITE_CONFI
13980 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e  G_PCACHE_HDRSZ].
13990 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  .** ^It is harml
139a0 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
139b0 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
139c0 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a  y,.** for the sz
139d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
139e0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63   larger than nec
139f0 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65  essary.  The pMe
13a00 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  m.** argument mu
13a10 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
13a20 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  ULL pointer or a
13a30 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
13a40 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
13a50 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
13a60 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
13a70 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69  N bytes, otherwi
13a80 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  se.** subsequent
13a90 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
13aa0 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e  efined..** ^When
13ab0 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c   pMem is not NUL
13ac0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73  L, SQLite will s
13ad0 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68 65  trive to use the
13ae0 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
13af0 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70  .** to satisfy p
13b00 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c  age cache needs,
13b10 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f   falling back to
13b20 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13b30 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65  ()] if.** a page
13b40 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c   cache line is l
13b50 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79  arger than sz by
13b60 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66  tes or if all of
13b70 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72   the pMem buffer
13b80 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65 64  .** is exhausted
13b90 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73  ..** ^If pMem is
13ba0 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e   NULL and N is n
13bb0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61  on-zero, then ea
13bc0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
13bd0 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61  ection.** does a
13be0 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61  n initial bulk a
13bf0 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61  llocation for pa
13c00 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a  ge cache memory.
13c10 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
13c20 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69  _malloc()] suffi
13c30 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68  cient for N cach
13c40 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20  e lines if N is 
13c50 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f  positive or.** o
13c60 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20  f -1024*N bytes 
13c70 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  if N is negative
13c80 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  , . ^If addition
13c90 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
13ca0 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
13cb0 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
13cc0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
13cd0 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f   initial.** allo
13ce0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c  cation, then SQL
13cf0 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
13d00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
13d10 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61  eparately for ea
13d20 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  ch.** additional
13d30 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64   cache line. </d
13d40 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13d50 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
13d60 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13d70 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
13d80 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
13d90 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
13da0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
13db0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
13dc0 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c  fer .** that SQL
13dd0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72  ite will use for
13de0 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
13df0 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
13e00 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62  ation needs.** b
13e10 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
13e20 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c  ided for by [SQL
13e30 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13e40 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49  CH] and.** [SQLI
13e50 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13e60 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51  CHE]..** ^The SQ
13e70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
13e80 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
13e90 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
13ea0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a  ite is compiled.
13eb0 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b  ** with either [
13ec0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
13ed0 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54  MSYS3] or [SQLIT
13ee0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
13ef0 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  ] and returns.**
13f00 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
13f10 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72  if invoked other
13f20 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  wise..** ^There 
13f30 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
13f40 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
13f50 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e  NFIG_HEAP:.** An
13f60 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
13f70 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
13f80 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
13f90 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
13fa0 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
13fb0 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
13fc0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13fd0 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
13fe0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
13ff0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
14000 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
14010 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
14020 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
14030 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
14040 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
14050 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
14060 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
14070 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
14080 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
14090 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
140a0 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
140b0 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
140c0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
140d0 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
140e0 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
140f0 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
14100 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
14110 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
14120 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14130 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
14140 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
14150 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
14160 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
14170 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
14180 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
14190 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
141a0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
141b0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
141c0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
141d0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
141e0 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
141f0 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
14200 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
14210 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
14220 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
14230 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
14240 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14250 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
14260 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14270 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
14280 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14290 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f  E_CONFIG_MUTEX o
142a0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
142b0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
142c0 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ich is a.** poin
142d0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
142e0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
142f0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14300 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
14310 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
14320 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69  cifies alternati
14330 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
14340 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
14350 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61  e used.** in pla
14360 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ce the mutex rou
14370 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
14380 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
14390 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
143a0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
143b0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
143c0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
143d0 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
143e0 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
143f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14400 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
14410 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14420 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
14430 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
14440 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
14450 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
14460 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
14470 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
14480 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
14490 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
144a0 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
144b0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
144c0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
144d0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
144e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
144f0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
14500 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
14510 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
14520 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
14530 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14540 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c  FIG_GETMUTEX]] <
14550 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14560 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
14570 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14580 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14590 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TEX option takes
145a0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
145b0 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
145c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
145d0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
145e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
145f0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
14600 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
14610 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14620 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
14630 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
14640 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
14650 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
14660 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
14670 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
14680 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
14690 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
146a0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
146b0 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
146c0 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
146d0 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
146e0 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
146f0 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
14700 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
14710 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
14720 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14730 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14740 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
14750 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14760 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
14770 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
14780 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
14790 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
147a0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
147b0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
147c0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
147d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
147e0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
147f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14800 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14810 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
14820 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
14830 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
14840 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14850 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
14860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14870 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
14880 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14890 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
148a0 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  DE option takes 
148b0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
148c0 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  at determine.** 
148d0 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65  the default size
148e0 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65   of lookaside me
148f0 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61  mory on each [da
14900 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14910 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  n]..** The first
14920 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
14930 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
14940 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
14950 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
14960 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
14970 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
14980 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
14990 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
149a0 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49  ction.)^  ^(SQLI
149b0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
149c0 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20  IDE.** sets the 
149d0 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
149e0 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
149f0 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
14a00 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
14a10 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c  * option to [sql
14a20 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
14a30 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
14a40 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
14a50 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
14a60 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
14a70 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
14a80 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
14a90 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14aa0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
14ab0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14ac0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
14ad0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14ae0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
14af0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14b00 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14b10 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
14b20 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
14b30 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14b40 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73  2] object.  This
14b50 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
14b60 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61  s.** the interfa
14b70 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70  ce to a custom p
14b80 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
14b90 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e  entation.)^.** ^
14ba0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
14bb0 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
14bc0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
14bd0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64  ds2] object.</dd
14be0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14bf0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14c00 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
14c10 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14c20 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
14c30 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14c40 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70  IG_GETPCACHE2 op
14c50 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14c60 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
14c70 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
14c80 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
14c90 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14ca0 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  2] object.  SQLi
14cb0 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20  te copies of.** 
14cc0 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 65  the current page
14cd0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
14ce0 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
14cf0 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
14d00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14d10 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e  ONFIG_LOG]] <dt>
14d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14d30 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54  G</dt>.** <dd> T
14d40 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14d50 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75  _LOG option is u
14d60 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
14d70 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67   the SQLite.** g
14d80 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67  lobal [error log
14d90 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49  ]..** (^The SQLI
14da0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
14db0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
14dc0 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e  rguments: a poin
14dd0 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63  ter to a.** func
14de0 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c  tion with a call
14df0 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f   signature of vo
14e00 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  id(*)(void*,int,
14e10 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a  const char*), .*
14e20 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20  * and a pointer 
14e30 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65  to void. ^If the
14e40 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
14e50 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69  r is not NULL, i
14e60 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  t is.** invoked 
14e70 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  by [sqlite3_log(
14e80 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61  )] to process ea
14e90 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74  ch logging event
14ea0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75  .  ^If the.** fu
14eb0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
14ec0 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c  s NULL, the [sql
14ed0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65  ite3_log()] inte
14ee0 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20  rface becomes a 
14ef0 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76  no-op..** ^The v
14f00 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74  oid pointer that
14f10 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
14f20 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54  rgument to SQLIT
14f30 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a  E_CONFIG_LOG is.
14f40 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  ** passed throug
14f50 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  h as the first p
14f60 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
14f70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
14f80 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
14f90 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20  nction whenever 
14fa0 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73  that function is
14fb0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20   invoked.  ^The 
14fc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14fd0 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65   to.** the logge
14fe0 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  r function is a 
14ff0 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73  copy of the firs
15000 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
15010 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
15020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  .** [sqlite3_log
15030 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20  ()] call and is 
15040 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61  intended to be a
15050 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
15060 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  r an.** [extende
15070 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20  d result code]. 
15080 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
15090 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
150a0 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a  the logger is.**
150b0 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74   log message aft
150c0 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69  er formatting vi
150d0 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  a [sqlite3_snpri
150e0 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53  ntf()]..** The S
150f0 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e  QLite logging in
15100 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
15110 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f  eentrant; the lo
15120 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gger function.**
15130 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
15140 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
15150 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79  t not invoke any
15160 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
15170 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69  e..** In a multi
15180 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
15190 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69  ation, the appli
151a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
151b0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
151c0 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  n must be thread
151d0 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  safe. </dd>.**.*
151e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
151f0 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_URI]] <dt>SQLI
15200 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a  TE_CONFIG_URI.**
15210 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54   <dd>^(The SQLIT
15220 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74  E_CONFIG_URI opt
15230 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15240 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
15250 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e  ype int..** If n
15260 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52  on-zero, then UR
15270 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
15280 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
15290 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
152a0 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65   is zero,.** the
152b0 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
152c0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
152d0 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68  led.)^ ^If URI h
152e0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
152f0 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20  lly.** enabled, 
15300 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61  all filenames pa
15310 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
15320 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
15330 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a  e3_open_v2()],.*
15340 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
15350 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
15360 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
15370 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
15380 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
15390 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
153a0 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
153b0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
153c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
153d0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
153e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
153f0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
15400 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69  opened. ^If it i
15410 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
15420 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
15430 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
15440 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
15450 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
15460 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
15470 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
15480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15490 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42  n is opened. ^(B
154a0 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
154b0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
154c0 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
154d0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
154e0 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
154f0 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
15500 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
15510 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
15520 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a  ol defined.)^.**
15530 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15540 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
15550 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
15560 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15570 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
15580 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15590 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
155a0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70  NG_INDEX_SCAN op
155b0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
155c0 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61  gle integer.** a
155d0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
155e0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
155f0 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64  a boolean in ord
15600 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  er to enable or 
15610 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75  disable.** the u
15620 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
15630 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
15640 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74  table scans in t
15650 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
15660 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  er..** ^The defa
15670 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64  ult setting is d
15680 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20  etermined.** by 
15690 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f  the [SQLITE_ALLO
156a0 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  W_COVERING_INDEX
156b0 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SCAN] compile-t
156c0 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69  ime option, or i
156d0 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61  s "on".** if tha
156e0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
156f0 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ption is omitted
15700 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79  ..** The ability
15710 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20   to disable the 
15720 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
15730 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
15740 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20   table scans.** 
15750 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20  is because some 
15760 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65  incorrectly code
15770 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61  d legacy applica
15780 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66  tions might malf
15790 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20  unction.** when 
157a0 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
157b0 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
157c0 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
157d0 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
157e0 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
157f0 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
15800 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
15810 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
15820 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
15830 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
15840 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
15850 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
15860 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15870 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
15880 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15890 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
158a0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
158b0 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
158c0 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
158d0 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
158e0 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
158f0 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
15900 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
15910 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
15920 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
15930 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
15940 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
15950 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64   no-ops..** </dd
15960 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15970 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d  _CONFIG_SQLLOG]]
15980 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
15990 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20  ONFIG_SQLLOG.** 
159a0 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
159b0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
159c0 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63  e if sqlite is c
159d0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
159e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
159f0 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70  LE_SQLLOG] pre-p
15a00 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
15a10 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73  efined. The firs
15a20 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  t argument shoul
15a30 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65  d.** be a pointe
15a40 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  r to a function 
15a50 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28  of type void(*)(
15a60 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63  void*,sqlite3*,c
15a70 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
15a80 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
15a90 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70  should be of typ
15aa0 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63  e (void*). The c
15ab0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
15ac0 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72  ed by the librar
15ad0 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65  y.** in three se
15ae0 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61  parate circumsta
15af0 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64  nces, identified
15b00 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61   by the value pa
15b10 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66  ssed as the.** f
15b20 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e  ourth parameter.
15b30 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
15b40 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74  arameter is 0, t
15b50 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
15b60 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70   connection.** p
15b70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
15b80 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73  ond argument has
15b90 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65   just been opene
15ba0 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67  d. The third arg
15bb0 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20  ument.** points 
15bc0 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74  to a buffer cont
15bd0 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20  aining the name 
15be0 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  of the main data
15bf0 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68  base file. If th
15c00 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
15c10 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e  meter is 1, then
15c20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
15c30 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72  nt that the thir
15c40 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70  d parameter.** p
15c50 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73  oints to has jus
15c60 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e  t been executed.
15c70 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72   Or, if the four
15c80 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15c90 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63  2, then.** the c
15ca0 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20  onnection being 
15cb0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
15cc0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
15cd0 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20  s being closed. 
15ce0 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  The.** third par
15cf0 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64  ameter is passed
15d00 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61   NULL In this ca
15d10 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  se.  An example 
15d20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a  of using this.**
15d30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15d40 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65  ption can be see
15d50 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73  n in the "test_s
15d60 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20  qllog.c" source 
15d70 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63  file in.** the c
15d80 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20  anonical SQLite 
15d90 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64  source tree.</dd
15da0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15db0 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15dc0 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
15dd0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15de0 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54  ZE.** <dd>^SQLIT
15df0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15e00 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d  ZE takes two 64-
15e10 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c  bit integer (sql
15e20 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75  ite3_int64) valu
15e30 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74  es.** that are t
15e40 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20  he default mmap 
15e50 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20  size limit (the 
15e60 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15e70 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d  for.** [PRAGMA m
15e80 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74  map_size]) and t
15e90 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
15ea0 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  ed mmap size lim
15eb0 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  it..** ^The defa
15ec0 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20  ult setting can 
15ed0 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  be overridden by
15ee0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
15ef0 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a  onnection using.
15f00 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50  ** either the [P
15f10 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
15f20 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20   command, or by 
15f30 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
15f40 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
15f50 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
15f60 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d  ol.  ^(The maxim
15f70 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
15f80 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  size.** will be 
15f90 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
15fa0 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 20  ed if necessary 
15fb0 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  so that it does 
15fc0 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a  not exceed the.*
15fd0 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  * compile-time m
15fe0 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65  aximum mmap size
15ff0 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
16000 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f  SQLITE_MAX_MMAP_
16010 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SIZE] compile-ti
16020 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  me option.)^.** 
16030 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d  ^If either argum
16040 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69  ent to this opti
16050 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  on is negative, 
16060 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65  then that argume
16070 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64  nt is.** changed
16080 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d   to its compile-
16090 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  time default..**
160a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
160b0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
160c0 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
160d0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
160e0 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  HEAPSIZE.** <dd>
160f0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
16100 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
16110 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  E option is only
16120 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
16130 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
16140 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20  led for Windows 
16150 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
16160 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70  _WIN32_MALLOC] p
16170 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
16180 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e  ro.** defined. ^
16190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
161a0 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b  N32_HEAPSIZE tak
161b0 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69  es a 32-bit unsi
161c0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c  gned integer val
161d0 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69  ue.** that speci
161e0 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  fies the maximum
161f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65   size of the cre
16200 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a  ated heap..**.**
16210 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16220 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a  _PCACHE_HDRSZ]].
16230 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16240 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16250 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
16260 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16270 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20  HE_HDRSZ option 
16280 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
16290 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
162a0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
162b0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
162c0 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61   writes into tha
162d0 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75  t integer the nu
162e0 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a  mber of extra.**
162f0 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20   bytes per page 
16300 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63  required for eac
16310 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54  h page in [SQLIT
16320 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
16330 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75  HE]..** The amou
16340 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63  nt of extra spac
16350 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63  e required can c
16360 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20  hange depending 
16370 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c  on the compiler,
16380 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66  .** target platf
16390 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20  orm, and SQLite 
163a0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  version..**.** [
163b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
163c0 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  MASZ]].** <dt>SQ
163d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
163e0 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
163f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
16400 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
16410 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
16420 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e  r which.** is an
16430 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
16440 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22  r and sets the "
16450 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  Minimum PMA Size
16460 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74  " for the multit
16470 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65  hreaded.** sorte
16480 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  r to that intege
16490 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  r.  The default 
164a0 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  minimum PMA Size
164b0 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a   is set by the.*
164c0 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52  * [SQLITE_SORTER
164d0 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d  _PMASZ] compile-
164e0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65  time option.  Ne
164f0 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61  w threads are la
16500 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c  unched.** to hel
16510 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72  p with sort oper
16520 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74  ations when mult
16530 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e  ithreaded sortin
16540 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20  g.** is enabled 
16550 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47  (using the [PRAG
16560 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d  MA threads] comm
16570 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f  and) and the amo
16580 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a  unt of content.*
16590 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65  * to be sorted e
165a0 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20  xceeds the page 
165b0 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d  size times the m
165c0 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a  inimum of the.**
165d0 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73   [PRAGMA cache_s
165e0 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64  ize] setting and
165f0 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a   this value..**.
16600 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16610 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
16620 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  L]].** <dt>SQLIT
16630 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
16640 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e  L_SPILL.** <dd>^
16650 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16660 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
16670 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
16680 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
16690 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65   which.** become
166a0 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74  s the [statement
166b0 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d   journal] spill-
166c0 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c  to-disk threshol
166d0 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65  d.  .** [Stateme
166e0 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65  nt journals] are
166f0 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20   held in memory 
16700 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65  until their size
16710 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65   (in bytes).** e
16720 78 63 65 65 64 73 20 74 68 69 73 20 74 68 72 65  xceeds this thre
16730 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20  shold, at which 
16740 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20 77  point they are w
16750 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a  ritten to disk..
16760 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68 72  ** Or if the thr
16770 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74  eshold is -1, st
16780 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73  atement journals
16790 20 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64   are always held
167a0 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20  .** exclusively 
167b0 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69  in memory..** Si
167c0 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65  nce many stateme
167d0 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65  nt journals neve
167e0 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20  r become large, 
167f0 73 65 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c  setting the spil
16800 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74  l.** threshold t
16810 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68 20 61  o a value such a
16820 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61  s 64KiB can grea
16830 74 6c 79 20 72 65 64 75 63 65 20 74 68 65 20 61  tly reduce the a
16840 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20  mount of.** I/O 
16850 72 65 71 75 69 72 65 64 20 74 6f 20 73 75 70 70  required to supp
16860 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f  ort statement ro
16870 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64  llback..** The d
16880 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
16890 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73   this setting is
168a0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74   controlled by t
168b0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54  he.** [SQLITE_ST
168c0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f  MTJRNL_SPILL] co
168d0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
168e0 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  n..** </dl>.*/.#
168f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16900 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
16910 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
16920 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16930 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
16940 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
16950 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16960 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
16970 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
16980 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16990 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
169a0 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
169b0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
169c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
169d0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
169e0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
169f0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
16a00 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16a10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
16a20 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
16a30 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
16a40 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
16a50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
16a60 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
16a70 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
16a80 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
16a90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16aa0 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
16ab0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
16ac0 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
16ad0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16ae0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
16af0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
16b00 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
16b10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
16b20 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
16b30 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
16b40 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
16b50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16b60 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
16b70 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
16b80 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
16b90 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
16ba0 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
16bb0 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
16bc0 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
16bd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16be0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16bf0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
16c00 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
16c10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16c20 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
16c30 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
16c40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16c50 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
16c60 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
16c70 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16c80 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
16c90 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
16ca0 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
16cb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
16cc0 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
16cd0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16ce0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16cf0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
16d00 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
16d10 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
16d20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16d30 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
16d40 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
16d50 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
16d60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16d70 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
16d80 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
16d90 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
16da0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16db0 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
16dc0 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
16dd0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
16de0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
16df0 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
16e00 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
16e10 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
16e20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16e30 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
16e40 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f  PSIZE      23  /
16e50 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
16e60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16e70 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16e80 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20  Z        24  /* 
16e90 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66  int *psz */.#def
16ea0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16eb0 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20  G_PMASZ         
16ec0 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73        25  /* uns
16ed0 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20  igned int szPma 
16ee0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16ef0 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
16f00 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20  L_SPILL      26 
16f10 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
16f20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16f30 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
16f40 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
16f50 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
16f60 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
16f70 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
16f80 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
16f90 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16fa0 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
16fb0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
16fc0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
16fd0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
16fe0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
16ff0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
17000 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17010 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
17020 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
17030 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
17040 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
17050 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
17060 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
17070 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
17080 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
17090 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
170a0 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
170b0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
170c0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
170d0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
170e0 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
170f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17100 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
17110 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
17120 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
17130 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
17140 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
17150 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
17160 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
17170 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
17180 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
17190 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
171a0 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
171b0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
171c0 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
171d0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
171e0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
171f0 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
17200 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
17210 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
17220 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
17230 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17240 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
17250 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
17260 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
17270 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
17280 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
17290 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
172a0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
172b0 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
172c0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
172d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
172e0 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
172f0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
17300 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
17310 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
17320 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
17330 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
17340 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
17350 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
17360 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
17370 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
17380 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
17390 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
173a0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
173b0 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
173c0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
173d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
173e0 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
173f0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
17400 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
17410 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
17420 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
17430 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
17440 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
17450 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
17460 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
17470 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
17480 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
17490 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
174a0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
174b0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
174c0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
174d0 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
174e0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
174f0 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
17500 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
17510 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
17520 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
17530 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
17540 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
17550 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
17560 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
17570 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
17580 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
17590 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
175a0 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
175b0 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
175c0 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
175d0 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
175e0 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
175f0 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
17600 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
17610 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
17620 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
17630 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
17640 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
17650 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
17660 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
17670 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
17680 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
17690 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
176a0 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
176b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
176c0 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
176d0 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
176e0 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
176f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
17700 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
17710 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
17720 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
17730 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
17740 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
17750 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
17760 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
17770 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
17780 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
17790 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
177a0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
177b0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
177c0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
177d0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
177e0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
177f0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
17800 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
17810 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
17820 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
17830 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
17840 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
17850 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
17860 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17870 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
17880 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
17890 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
178a0 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
178b0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
178c0 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
178d0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
178e0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
178f0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
17900 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
17910 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
17920 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
17930 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
17940 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
17950 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17960 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17970 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
17980 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
17990 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
179a0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
179b0 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
179c0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
179d0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
179e0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
179f0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17a00 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17a10 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17a20 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
17a30 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
17a40 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
17a50 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
17a60 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
17a70 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
17a80 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
17a90 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
17aa0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17ab0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17ac0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
17ad0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
17ae0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
17af0 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
17b00 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
17b10 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
17b20 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
17b30 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17b40 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
17b50 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
17b60 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
17b70 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
17b80 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
17b90 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
17ba0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
17bb0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54  CONFIG_ENABLE_FT
17bc0 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74  S3_TOKENIZER</dt
17bd0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17be0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17bf0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
17c00 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75  ble the two-argu
17c10 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20  ment.** version 
17c20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b  of the [fts3_tok
17c30 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69  enizer()] functi
17c40 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61 72 74  on which is part
17c50 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33   of the.** [FTS3
17c60 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72  ] full-text sear
17c70 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73  ch engine extens
17c80 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  ion..** There sh
17c90 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
17ca0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17cb0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
17cc0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
17cd0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
17ce0 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33   to disable fts3
17cf0 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a  _tokenizer() or.
17d00 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
17d10 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  nable fts3_token
17d20 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69  izer() or negati
17d30 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
17d40 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61  setting.** uncha
17d50 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
17d60 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
17d70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17d80 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
17d90 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
17da0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
17db0 63 61 74 65 20 77 68 65 74 68 65 72 20 66 74 73  cate whether fts
17dc0 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64  3_tokenizer is d
17dd0 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
17de0 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
17df0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17e00 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17e10 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
17e20 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
17e30 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77  ich case the new
17e40 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
17e50 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
17e60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
17e70 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
17e80 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e  NABLE_LOAD_EXTEN
17e90 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SION</dt>.** <dd
17ea0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
17eb0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
17ec0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
17ed0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
17ee0 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e  tension()].** in
17ef0 74 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64  terface independ
17f00 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f  ently of the [lo
17f10 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
17f20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
17f30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e   The [sqlite3_en
17f40 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
17f50 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c  ion()] API enabl
17f60 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62  es or disables b
17f70 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49  oth the.** C-API
17f80 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
17f90 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20  xtension()] and 
17fa0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
17fb0 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
17fc0 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  ()]..** There sh
17fd0 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
17fe0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17ff0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69  ..** When the fi
18000 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
18010 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
18020 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74  s 1, then only t
18030 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65  he C-API is.** e
18040 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53  nabled and the S
18050 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61  QL function rema
18060 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49  ins disabled.  I
18070 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67 6d  f the first argm
18080 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69  ent to.** this i
18090 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74  nterface is 0, t
180a0 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41  hen both the C-A
180b0 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  PI and the SQL f
180c0 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61  unction are disa
180d0 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  bled..** If the 
180e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
180f0 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68  s -1, then no ch
18100 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74  anges are made t
18110 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65  o state of eithe
18120 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f  r the.** C-API o
18130 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  r the SQL functi
18140 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  on..** The secon
18150 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18160 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18170 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
18180 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
18190 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
181a0 74 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69  te whether [sqli
181b0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
181c0 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  on()] interface.
181d0 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f  ** is disabled o
181e0 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77  r enabled follow
181f0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
18200 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18210 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61  eter may.** be a
18220 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
18230 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
18240 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
18250 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
18260 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  k..** </dd>.**.*
18270 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
18280 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18290 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
182a0 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a           1001 /*
182b0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
182c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
182d0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
182e0 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20  _FKEY           
182f0 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1002 /* int int*
18300 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18310 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18320 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  LE_TRIGGER      
18330 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e    1003 /* int in
18340 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18350 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18360 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49  ABLE_FTS3_TOKENI
18370 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20  ZER 1004 /* int 
18380 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
18390 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
183a0 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45  ENABLE_LOAD_EXTE
183b0 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e  NSION 1005 /* in
183c0 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
183d0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
183e0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
183f0 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
18400 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  des.** METHOD: s
18410 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
18420 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
18430 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
18440 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
18450 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
18460 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
18470 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
18480 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
18490 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
184a0 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
184b0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
184c0 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
184d0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
184e0 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ty..*/.SQLITE_AP
184f0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
18500 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 74  CALL sqlite3_ext
18510 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
18520 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
18530 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
18540 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
18550 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d  nsert Rowid.** M
18560 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
18570 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
18580 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20   in most SQLite 
18590 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66  tables (except f
185a0 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  or [WITHOUT ROWI
185b0 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61  D] tables).** ha
185c0 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
185d0 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
185e0 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
185f0 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
18600 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
18610 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
18620 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
18630 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
18640 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
18650 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
18660 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
18670 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
18680 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
18690 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
186a0 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
186b0 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
186c0 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
186d0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
186e0 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
186f0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
18700 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
18710 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
18720 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  The sqlite3_last
18730 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
18740 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
18750 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
18760 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72  f the .** most r
18770 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
18780 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61   [INSERT] into a
18790 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20   rowid table or 
187a0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
187b0 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63  ** on database c
187c0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20  onnection D..** 
187d0 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
187e0 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
187f0 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63  bles are not rec
18800 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f  orded..** ^If no
18810 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
18820 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
18830 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20   tables.** have 
18840 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
18850 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18860 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20  nnection D, .** 
18870 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73  then sqlite3_las
18880 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
18890 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
188a0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
188b0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
188c0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f  thin a trigger o
188d0 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74  r within a [virt
188e0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65  ual table].** me
188f0 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20  thod, then this 
18900 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
18910 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
18920 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
18930 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ** row as long a
18940 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  s the trigger or
18950 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
18960 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67  ethod is running
18970 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
18980 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
18990 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
189a0 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75  d ends, the valu
189b0 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62  e returned .** b
189c0 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
189d0 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69  everts to what i
189e0 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65  t was before the
189f0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
18a00 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74  ual.** table met
18a10 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a  hod began.)^.**.
18a20 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
18a30 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
18a40 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
18a50 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
18a60 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
18a70 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
18a80 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
18a90 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
18aa0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
18ab0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
18ac0 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
18ad0 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
18ae0 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
18af0 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
18b00 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
18b10 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
18b20 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
18b30 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
18b40 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
18b50 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
18b60 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
18b70 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
18b80 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
18b90 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
18ba0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
18bb0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
18bc0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
18bd0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
18be0 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
18bf0 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
18c00 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
18c10 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
18c20 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
18c30 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
18c40 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
18c50 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
18c60 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
18c70 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
18c80 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
18c90 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
18ca0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
18cb0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
18cc0 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
18cd0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
18ce0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
18cf0 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
18d00 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
18d10 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
18d20 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
18d30 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
18d40 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
18d50 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
18d60 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
18d70 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
18d80 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
18d90 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
18da0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
18db0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
18dc0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
18dd0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
18de0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
18df0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
18e00 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
18e10 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
18e20 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
18e30 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
18e40 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
18e50 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
18e60 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
18e70 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
18e80 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
18e90 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  wid]..*/.SQLITE_
18ea0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
18eb0 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  4 SQLITE_STDCALL
18ec0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
18ed0 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
18ee0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
18ef0 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
18f00 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
18f10 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
18f20 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
18f30 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
18f40 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
18f50 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
18f60 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  fied, inserted o
18f70 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
18f80 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
18f90 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
18fa0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
18fb0 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
18fc0 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  t on the databas
18fd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65  e connection spe
18fe0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e  cified by the on
18ff0 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ly parameter..**
19000 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20   ^Executing any 
19010 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51  other type of SQ
19020 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
19030 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20   not modify the 
19040 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
19050 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
19060 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  on..**.** ^Only 
19070 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72  changes made dir
19080 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53  ectly by the INS
19090 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
190a0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
190b0 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
190c0 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68  d - auxiliary ch
190d0 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
190e0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
190f0 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a  | triggers], .**
19100 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
19110 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41  tions] or [REPLA
19120 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
19130 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f  esolution are no
19140 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
19150 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
19160 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
19170 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20  ercepted by .** 
19180 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
19190 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46  ger | INSTEAD OF
191a0 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e   triggers] are n
191b0 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65  ot counted. ^The
191c0 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72   value .** retur
191d0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
191e0 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61  hanges() immedia
191f0 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e  tely after an IN
19200 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
19210 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65  .** DELETE state
19220 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69  ment run on a vi
19230 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  ew is always zer
19240 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  o. Only changes 
19250 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a  made to real .**
19260 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e   tables are coun
19270 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67  ted..**.** Thing
19280 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c  s are more compl
19290 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71  icated if the sq
192a0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
192b0 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65  function is.** e
192c0 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20  xecuted while a 
192d0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
192e0 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73  is running. This
192f0 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74   may happen if t
19300 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  he.** program us
19310 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  es the [changes(
19320 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c  ) SQL function],
19330 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65   or if some othe
19340 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  r callback.** fu
19350 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73  nction invokes s
19360 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
19370 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e   directly. Essen
19380 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c  tially:.** .** <
19390 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ul>.**   <li> ^(
193a0 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20  Before entering 
193b0 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
193c0 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  m the value retu
193d0 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  rned by.**      
193e0 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65    sqlite3_change
193f0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  s() function is 
19400 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65  saved. After the
19410 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
19420 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20   .**        has 
19430 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72  finished, the or
19440 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20  iginal value is 
19450 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a  restored.)^.** .
19460 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68  **   <li> ^(With
19470 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  in a trigger pro
19480 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54  gram each INSERT
19490 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c  , UPDATE and DEL
194a0 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73  ETE .**        s
194b0 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68  tatement sets th
194c0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
194d0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
194e0 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
194f0 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e   upon completion
19500 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63   as normal. Of c
19510 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75  ourse, this valu
19520 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75  e will not inclu
19530 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e  de .**        an
19540 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72  y changes perfor
19550 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67  med by sub-trigg
19560 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69  ers, as the sqli
19570 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
19580 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77  *        value w
19590 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64  ill be saved and
195a0 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20   restored after 
195b0 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72  each sub-trigger
195c0 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c   has run.)^.** <
195d0 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69  /ul>.** .** ^Thi
195e0 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20  s means that if 
195f0 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51  the changes() SQ
19600 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73  L function (or s
19610 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a  imilar) is used.
19620 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ** by the first 
19630 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
19640 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
19650 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
19660 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75  ger, it .** retu
19670 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73  rns the value as
19680 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61   set when the ca
19690 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  lling statement 
196a0 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e  began executing.
196b0 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73  .** ^If it is us
196c0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
196d0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73   or subsequent s
196e0 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69  uch statement wi
196f0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a  thin a trigger .
19700 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20  ** program, the 
19710 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72  value returned r
19720 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62  eflects the numb
19730 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
19740 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70  ied by the .** p
19750 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20  revious INSERT, 
19760 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
19770 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
19780 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  n the same trigg
19790 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  er..**.** See al
197a0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
197b0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
197c0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
197d0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
197e0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
197f0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
19800 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
19810 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
19820 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
19830 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
19840 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19850 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
19860 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
19870 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
19880 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
19890 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
198a0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
198b0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
198c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
198d0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
198e0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
198f0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
19900 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
19910 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
19920 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
19930 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
19940 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
19950 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74   returns the tot
19960 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  al number of row
19970 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69  s inserted, modi
19980 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  fied or.** delet
19990 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52  ed by all [INSER
199a0 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  T], [UPDATE] or 
199b0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
199c0 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a  nts completed.**
199d0 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62   since the datab
199e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
199f0 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75  as opened, inclu
19a00 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75  ding those execu
19a10 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ted as.** part o
19a20 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  f trigger progra
19a30 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61  ms. ^Executing a
19a40 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
19a50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
19a60 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63  * does not affec
19a70 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
19a80 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
19a90 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e  total_changes().
19aa0 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  .** .** ^Changes
19ab0 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
19ac0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
19ad0 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75  tions] are inclu
19ae0 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f  ded in the.** co
19af0 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d  unt, but those m
19b00 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52  ade as part of R
19b10 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
19b20 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
19b30 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65  .** not. ^Change
19b40 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
19b50 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
19b60 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74   by INSTEAD OF t
19b70 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20  riggers .** are 
19b80 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
19b90 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
19ba0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
19bb0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
19bc0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
19bd0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
19be0 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
19bf0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
19c00 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
19c10 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
19c20 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
19c30 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
19c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
19c50 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
19c60 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
19c70 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
19c80 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
19c90 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
19ca0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
19cb0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
19cc0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
19cd0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
19ce0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
19cf0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
19d00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19d10 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
19d20 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
19d30 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
19d40 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
19d50 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
19d60 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
19d70 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
19d80 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
19d90 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
19da0 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
19db0 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
19dc0 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
19dd0 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
19de0 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
19df0 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
19e00 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
19e10 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
19e20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
19e30 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
19e40 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
19e50 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
19e60 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
19e70 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
19e80 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
19e90 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
19ea0 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
19eb0 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
19ec0 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
19ed0 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
19ee0 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
19ef0 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
19f00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
19f10 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
19f20 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
19f30 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
19f40 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
19f50 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
19f60 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
19f70 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
19f80 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
19f90 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
19fa0 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
19fb0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
19fc0 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
19fd0 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
19fe0 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
19ff0 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
1a000 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
1a010 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
1a020 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
1a030 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
1a040 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
1a050 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
1a060 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
1a070 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
1a080 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
1a090 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
1a0a0 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
1a0b0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
1a0c0 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
1a0d0 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
1a0e0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
1a0f0 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
1a100 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
1a110 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
1a120 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
1a130 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1a140 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
1a150 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
1a160 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
1a170 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
1a180 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1a190 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
1a1a0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
1a1b0 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
1a1c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1a1d0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1a1e0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1a1f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1a200 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
1a210 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
1a220 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
1a230 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
1a240 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
1a250 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
1a260 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
1a270 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1a280 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
1a290 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
1a2a0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1a2b0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1a2c0 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
1a2d0 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
1a2e0 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
1a2f0 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
1a300 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1a310 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
1a320 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
1a330 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
1a340 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
1a350 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
1a360 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1a370 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
1a380 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
1a390 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
1a3a0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1a3b0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1a3c0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1a3d0 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
1a3e0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
1a3f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a400 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
1a410 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1a420 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
1a430 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
1a440 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
1a450 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  appen..*/.SQLITE
1a460 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
1a470 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1a480 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
1a490 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1a4a0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
1a4b0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
1a4c0 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
1a4d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1a4e0 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
1a4f0 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
1a500 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
1a510 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
1a520 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
1a530 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
1a540 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
1a550 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1a560 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
1a570 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
1a580 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
1a590 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
1a5a0 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
1a5b0 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
1a5c0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1a5d0 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
1a5e0 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
1a5f0 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
1a600 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
1a610 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
1a620 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
1a630 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
1a640 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
1a650 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
1a660 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
1a670 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
1a680 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
1a690 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
1a6a0 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
1a6b0 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
1a6c0 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
1a6d0 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
1a6e0 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
1a6f0 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
1a700 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
1a710 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
1a720 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
1a730 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
1a740 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
1a750 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
1a760 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
1a770 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
1a780 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
1a790 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
1a7a0 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
1a7b0 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
1a7c0 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
1a7d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
1a7e0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1a7f0 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
1a800 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
1a810 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
1a820 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
1a830 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
1a840 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
1a850 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1a860 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
1a870 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
1a880 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
1a890 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
1a8a0 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
1a8b0 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
1a8c0 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
1a8d0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
1a8e0 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
1a8f0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
1a900 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
1a910 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
1a920 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1a930 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
1a940 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
1a950 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
1a960 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
1a970 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
1a980 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
1a990 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
1a9a0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
1a9b0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
1a9c0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1a9d0 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
1a9e0 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
1a9f0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1aa00 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
1aa10 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
1aa20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1aa30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1aa40 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
1aa50 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1aa60 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
1aa70 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
1aa80 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1aa90 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
1aaa0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1aab0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
1aac0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
1aad0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
1aae0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1aaf0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1ab00 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1ab10 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
1ab20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
1ab30 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
1ab40 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1ab50 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
1ab60 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
1ab70 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
1ab80 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
1ab90 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
1aba0 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f   Errors.** KEYWO
1abb0 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c  RDS: {busy-handl
1abc0 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75  er callback} {bu
1abd0 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d  sy handler}.** M
1abe0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1abf0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1ac00 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
1ac10 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65  ,X,P) routine se
1ac20 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
1ac30 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74  nction X.** that
1ac40 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
1ac50 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
1ac60 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  P whenever.** an
1ac70 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
1ac80 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74   to access a dat
1ac90 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f  abase table asso
1aca0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b  ciated with.** [
1acb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1acc0 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74  ion] D when anot
1acd0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
1ace0 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65   process has the
1acf0 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a   table locked..*
1ad00 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75  * The sqlite3_bu
1ad10 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74  sy_handler() int
1ad20 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
1ad30 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b  o implement.** [
1ad40 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1ad50 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41  eout()] and [PRA
1ad60 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1ad70 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
1ad80 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
1ad90 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
1ada0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73  LITE_BUSY].** is
1adb0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1adc0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
1add0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
1ade0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
1adf0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
1ae00 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
1ae10 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
1ae20 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1ae30 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
1ae40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1ae50 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1ae60 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1ae70 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
1ae80 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
1ae90 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
1aea0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
1aeb0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1aec0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
1aed0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
1aee0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1aef0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
1af00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
1af10 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
1af20 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
1af30 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72   been invoked pr
1af40 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65  eviously for the
1af50 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76   same locking ev
1af60 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
1af70 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
1af80 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
1af90 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
1afa0 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
1afb0 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
1afc0 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
1afd0 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65  LITE_BUSY] is re
1afe0 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65  turned.** to the
1aff0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a   application..**
1b000 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
1b010 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1b020 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
1b030 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
1b040 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68  ade to access th
1b050 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  e database and t
1b060 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
1b070 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
1b080 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
1b090 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
1b0a0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
1b0b0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
1b0c0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
1b0d0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
1b0e0 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
1b0f0 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
1b100 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
1b110 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
1b120 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
1b130 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
1b140 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
1b150 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
1b160 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  ].** to the appl
1b170 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20  ication instead 
1b180 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
1b190 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1b1a0 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
1b1b0 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
1b1c0 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
1b1d0 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
1b1e0 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
1b1f0 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
1b200 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
1b210 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
1b220 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
1b230 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
1b240 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
1b250 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
1b260 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
1b270 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
1b280 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1b290 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
1b2a0 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
1b2b0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
1b2c0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
1b2d0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
1b2e0 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
1b2f0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1b300 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
1b310 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
1b320 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
1b330 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1b340 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
1b350 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
1b360 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
1b370 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
1b380 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
1b390 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
1b3a0 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
1b3b0 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
1b3c0 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
1b3d0 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
1b3e0 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
1b3f0 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
1b400 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1b410 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
1b420 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1b430 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
1b440 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s NULL..**.** ^(
1b450 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1b460 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1b470 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
1b480 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
1b490 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b4a0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
1b4b0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
1b4c0 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
1b4d0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
1b4e0 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
1b4f0 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
1b500 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1b510 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61  ()].** or evalua
1b520 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73  ting [PRAGMA bus
1b530 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c  y_timeout=N] wil
1b540 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  l change the.** 
1b550 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64  busy handler and
1b560 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20   thus clear any 
1b570 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62  previously set b
1b580 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
1b590 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
1b5a0 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
1b5b0 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
1b5c0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
1b5d0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
1b5e0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1b5f0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1b600 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65  andler.  In othe
1b610 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20  r words,.** the 
1b620 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1b630 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20  not reentrant.  
1b640 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
1b650 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
1b660 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
1b670 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
1b680 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
1b690 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
1b6a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1b6b0 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
1b6c0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
1b6d0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1b6e0 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49  handler..*/.SQLI
1b6f0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
1b700 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1b710 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
1b720 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
1b730 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
1b740 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1b750 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
1b760 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f  Timeout.** METHO
1b770 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1b780 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
1b790 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
1b7a0 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
1b7b0 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
1b7c0 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
1b7d0 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
1b7e0 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
1b7f0 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
1b800 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
1b810 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
1b820 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
1b830 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
1b840 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1b850 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
1b860 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
1b870 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
1b880 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1b890 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
1b8a0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
1b8b0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
1b8c0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
1b8d0 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
1b8e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1b8f0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1b900 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1b910 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
1b920 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
1b930 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
1b940 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
1b950 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
1b960 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1b970 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1b980 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
1b990 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1b9a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b9b0 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e  on] at any given
1b9c0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
1b9d0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1b9e0 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
1b9f0 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
1ba00 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1ba10 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
1ba20 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
1ba30 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
1ba40 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1ba50 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  cleared.)^.**.**
1ba60 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41   See also:  [PRA
1ba70 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1ba80 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
1ba90 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
1baa0 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  LL sqlite3_busy_
1bab0 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
1bac0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
1bad0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
1bae0 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
1baf0 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
1bb00 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ries.** METHOD: 
1bb10 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
1bb20 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
1bb30 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
1bb40 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
1bb50 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1bb60 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
1bb70 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1bb80 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
1bb90 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
1bba0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
1bbb0 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
1bbc0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
1bbd0 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
1bbe0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1bbf0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
1bc00 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
1bc10 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
1bc20 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
1bc30 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
1bc40 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
1bc50 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
1bc60 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
1bc70 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
1bc80 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
1bc90 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
1bca0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
1bcb0 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
1bcc0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1bcd0 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
1bce0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
1bcf0 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
1bd00 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
1bd10 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
1bd20 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
1bd30 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1bd40 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1bd50 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
1bd60 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
1bd70 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1bd80 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
1bd90 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
1bda0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
1bdb0 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
1bdc0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
1bdd0 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
1bde0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1bdf0 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
1be00 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
1be10 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1be20 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1be30 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1be40 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1be50 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1be60 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1be70 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1be80 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1be90 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1bea0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1beb0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1bec0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1bed0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1bee0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1bef0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1bf00 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1bf10 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1bf20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1bf30 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1bf40 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1bf50 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1bf60 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1bf70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1bf80 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1bf90 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1bfa0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1bfb0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1bfc0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1bfd0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1bfe0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1bff0 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1c000 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1c010 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1c020 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1c030 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1c040 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1c050 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1c060 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1c070 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1c080 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1c090 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1c0a0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1c0b0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1c0c0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1c0d0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1c0e0 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1c0f0 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1c100 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1c110 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1c120 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1c130 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1c140 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1c150 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1c160 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1c170 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1c180 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1c190 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1c1a0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1c1b0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c1c0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1c1d0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1c1e0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1c1f0 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1c200 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1c210 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1c220 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1c230 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1c240 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1c250 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1c260 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1c270 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1c280 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1c290 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1c2a0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1c2b0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1c2c0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1c2d0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1c2e0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1c2f0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1c300 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1c310 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1c320 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1c330 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1c340 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1c350 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1c360 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1c370 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1c380 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1c390 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1c3a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1c3b0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1c3c0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1c3d0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1c3e0 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1c3f0 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1c400 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1c410 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1c420 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1c430 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1c440 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1c450 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1c460 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1c470 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1c480 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1c490 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1c4a0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1c4b0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1c4c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c4d0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1c4e0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1c4f0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1c500 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1c510 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1c520 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1c530 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1c540 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1c550 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1c560 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1c570 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1c580 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1c590 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1c5a0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1c5b0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1c5c0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1c5d0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1c5e0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1c5f0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1c600 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1c610 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1c620 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1c630 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1c640 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1c650 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1c660 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1c670 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1c680 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1c690 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1c6a0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1c6b0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1c6c0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1c6d0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1c6e0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1c6f0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1c700 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1c710 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1c720 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1c730 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1c740 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1c750 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1c760 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1c770 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1c780 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1c790 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
1c7a0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
1c7b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1c7c0 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
1c7d0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
1c7e0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
1c7f0 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
1c800 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
1c810 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
1c820 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
1c830 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1c840 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
1c850 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
1c860 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
1c870 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1c880 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
1c890 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
1c8a0 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
1c8b0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
1c8c0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1c8d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1c8e0 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  id SQLITE_STDCAL
1c8f0 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  L sqlite3_free_t
1c900 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
1c910 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
1c920 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
1c930 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
1c940 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1c950 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1c960 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
1c970 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
1c980 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
1c990 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
1c9a0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1c9b0 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ary..** These ro
1c9c0 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e  utines understan
1c9d0 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f  d most of the co
1c9e0 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74  mmon K&R formatt
1c9f0 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20  ing options,.** 
1ca00 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69  plus some additi
1ca10 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72  onal non-standar
1ca20 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69  d formats, detai
1ca30 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f  led below..** No
1ca40 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20  te that some of 
1ca50 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65  the more obscure
1ca60 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1ca70 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a  ons from recent.
1ca80 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61  ** C-library sta
1ca90 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74  ndards are omitt
1caa0 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70  ed from this imp
1cab0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a  lementation..**.
1cac0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1cad0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1cae0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1caf0 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1cb00 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1cb10 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1cb20 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1cb30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
1cb40 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
1cb50 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1cb60 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
1cb70 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
1cb80 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1cb90 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
1cba0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
1cbb0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1cbc0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
1cbd0 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
1cbe0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
1cbf0 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
1cc00 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
1cc10 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
1cc20 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1cc30 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1cc40 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
1cc50 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
1cc60 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
1cc70 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
1cc80 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
1cc90 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
1cca0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
1ccb0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1ccc0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
1ccd0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
1cce0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
1ccf0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
1cd00 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
1cd10 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
1cd20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
1cd30 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
1cd40 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
1cd50 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
1cd60 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
1cd70 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
1cd80 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
1cd90 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
1cda0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
1cdb0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
1cdc0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1cdd0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
1cde0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
1cdf0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
1ce00 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
1ce10 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
1ce20 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
1ce30 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
1ce40 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
1ce50 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1ce60 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
1ce70 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
1ce80 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
1ce90 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
1cea0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
1ceb0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1cec0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1ced0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
1cee0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1cef0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
1cf00 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
1cf10 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
1cf20 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
1cf30 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
1cf40 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
1cf50 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
1cf60 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
1cf70 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
1cf80 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
1cf90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
1cfa0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
1cfb0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
1cfc0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
1cfd0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
1cfe0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
1cff0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
1d000 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
1d010 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
1d020 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
1d030 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
1d040 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1d050 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
1d060 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
1d070 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
1d080 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1d090 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
1d0a0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
1d0b0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
1d0c0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
1d0d0 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
1d0e0 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
1d0f0 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
1d100 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1d110 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
1d120 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
1d130 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
1d140 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
1d150 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
1d160 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25  e "%q", "%Q", "%
1d170 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  w" and "%z" opti
1d180 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
1d190 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
1d1a0 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
1d1b0 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
1d1c0 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
1d1d0 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
1d1e0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
1d1f0 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
1d200 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
1d210 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
1d220 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
1d230 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
1d240 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1d250 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
1d260 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
1d270 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
1d280 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
1d290 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
1d2a0 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
1d2b0 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
1d2c0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
1d2d0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
1d2e0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
1d2f0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
1d300 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
1d310 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1d320 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1d330 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
1d340 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
1d350 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1d360 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
1d370 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
1d380 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
1d390 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
1d3a0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1d3b0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1d3c0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1d3d0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1d3e0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1d3f0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
1d400 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1d410 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1d420 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1d430 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1d440 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1d450 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
1d460 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
1d470 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
1d480 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
1d490 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
1d4a0 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
1d4b0 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
1d4c0 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
1d4d0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1d4e0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1d4f0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1d500 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
1d510 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
1d520 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1d530 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1d540 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
1d550 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
1d560 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
1d570 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
1d580 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
1d590 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
1d5a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1d5b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1d5c0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1d5d0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
1d5e0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
1d5f0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1d600 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
1d610 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
1d620 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
1d630 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
1d640 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
1d650 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
1d660 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
1d670 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1d680 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
1d690 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
1d6a0 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
1d6b0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
1d6c0 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
1d6d0 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
1d6e0 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
1d6f0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
1d700 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
1d710 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
1d720 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
1d730 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
1d740 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
1d750 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
1d760 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
1d770 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
1d780 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
1d790 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
1d7a0 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
1d7b0 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
1d7c0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1d7d0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1d7e0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1d7f0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1d800 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
1d810 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1d820 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1d830 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1d840 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1d850 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1d860 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1d870 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
1d880 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
1d890 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
1d8a0 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
1d8b0 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
1d8c0 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
1d8d0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
1d8e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1d8f0 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61  ^(The "%w" forma
1d900 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1d910 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74  like "%q" except
1d920 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73   that it expects
1d930 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69   to.** be contai
1d940 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c  ned within doubl
1d950 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64  e-quotes instead
1d960 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65   of single quote
1d970 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63  s, and it.** esc
1d980 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d  apes the double-
1d990 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20  quote character 
1d9a0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73  instead of the s
1d9b0 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63  ingle-quote.** c
1d9c0 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65  haracter.)^  The
1d9d0 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1d9e0 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e   option is inten
1d9f0 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69  ded for safely i
1da00 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c  nserting.** tabl
1da10 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  e and column nam
1da20 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72  es into a constr
1da30 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  ucted SQL statem
1da40 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ent..**.** ^(The
1da50 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1da60 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1da70 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1da80 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1da90 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1daa0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1dab0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1dac0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1dad0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1dae0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1daf0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1db00 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ng.)^.*/.SQLITE_
1db10 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45  API char *SQLITE
1db20 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 6d  _CDECL sqlite3_m
1db30 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1db40 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  r*,...);.SQLITE_
1db50 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45  API char *SQLITE
1db60 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1db70 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1db80 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1db90 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1dba0 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73   *SQLITE_CDECL s
1dbb0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1dbc0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1dbd0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c  char*, ...);.SQL
1dbe0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51  ITE_API char *SQ
1dbf0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1dc00 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1dc10 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1dc20 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1dc30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1dc40 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1dc50 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1dc60 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1dc70 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1dc80 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1dc90 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1dca0 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1dcb0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1dcc0 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1dcd0 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1dce0 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1dcf0 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1dd00 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1dd10 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1dd20 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1dd30 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1dd40 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1dd50 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1dd60 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1dd70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1dd80 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1dd90 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1dda0 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1ddb0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1ddc0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1ddd0 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1dde0 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1ddf0 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1de00 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1de10 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1de20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1de30 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1de40 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1de50 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1de60 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1de70 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1de80 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1de90 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1dea0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1deb0 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1dec0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
1ded0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1dee0 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f  64(N) routine wo
1def0 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a  rks just like.**
1df00 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1df10 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1df20 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
1df30 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69  64-bit integer i
1df40 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73  nstead.** of a s
1df50 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74  igned 32-bit int
1df60 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  eger..**.** ^Cal
1df70 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1df80 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1df90 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1dfa0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1dfb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1dfc0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1dfd0 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1dfe0 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1dff0 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1e000 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1e010 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1e020 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1e030 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1e040 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1e050 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1e060 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1e070 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1e080 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1e090 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1e0a0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1e0b0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1e0c0 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1e0d0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1e0e0 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1e0f0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1e100 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1e110 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1e120 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1e130 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1e140 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1e150 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1e160 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1e170 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1e180 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1e190 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1e1a0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1e1b0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1e1c0 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1e1d0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1e1e0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1e1f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1e200 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e210 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1e220 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1e230 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1e240 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1e250 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62  llocation X to b
1e260 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1e270 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58  es..** ^If the X
1e280 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1e290 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1e2a0 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  N).** is a NULL 
1e2b0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1e2c0 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1e2d0 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1e2e0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1e2f0 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74  loc(N)..** ^If t
1e300 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
1e310 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1e320 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f  c(X,N) is zero o
1e330 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1e340 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1e350 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1e360 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1e370 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58  * sqlite3_free(X
1e380 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1e390 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1e3a0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1e3b0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1e3c0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1e3d0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1e3e0 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ize or NULL if i
1e3f0 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
1e400 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  ry is available.
1e410 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1e420 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1e430 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1e440 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1e450 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1e460 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1e470 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1e480 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1e490 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1e4a0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1e4b0 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68  lloc(X,N) and th
1e4c0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1e4d0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1e4e0 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1e4f0 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1e500 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70   NULL and N is p
1e510 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68  ositive, then th
1e520 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63  e.** prior alloc
1e530 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65  ation is not fre
1e540 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1e550 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1e560 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73  (X,N) interfaces
1e570 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
1e580 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  as.** sqlite3_re
1e590 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70  alloc(X,N) excep
1e5a0 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34  t that N is a 64
1e5b0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1e5c0 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1e5d0 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
1e5e0 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1e5f0 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65  ** ^If X is a me
1e600 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1e610 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
1e620 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1e630 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  _malloc(),.** sq
1e640 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1e650 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1e660 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  c(), or sqlite3_
1e670 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65  realloc64(), the
1e680 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1e690 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  ze(X) returns th
1e6a0 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d  e size of that m
1e6b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1e6c0 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54   in bytes..** ^T
1e6d0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1e6e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69  d by sqlite3_msi
1e6f0 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c  ze(X) might be l
1e700 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e  arger than the n
1e710 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
1e720 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e  s requested when
1e730 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64   X was allocated
1e740 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55  .  ^If X is a NU
1e750 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
1e760 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1e770 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (X) returns zero
1e780 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74  .  If X points t
1e790 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74  o something that
1e7a0 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62   is not.** the b
1e7b0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f  eginning of memo
1e7c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f  ry allocation, o
1e7d0 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74  r if it points t
1e7e0 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20  o a formerly.** 
1e7f0 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  valid memory all
1e800 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73  ocation that has
1e810 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c   now been freed,
1e820 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1e830 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  or.** of sqlite3
1e840 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64  _msize(X) is und
1e850 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69  efined and possi
1e860 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
1e870 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1e880 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1e890 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c  e3_malloc(), sql
1e8a0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a  ite3_realloc(),.
1e8b0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1e8c0 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  c64(), and sqlit
1e8d0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a  e3_realloc64().*
1e8e0 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
1e8f0 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
1e900 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
1e910 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
1e920 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
1e930 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
1e940 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
1e950 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
1e960 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
1e970 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
1e980 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1e990 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
1e9a0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
1e9b0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
1e9c0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
1e9d0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
1e9e0 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
1e9f0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
1ea00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1ea10 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1ea20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
1ea30 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
1ea40 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
1ea50 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
1ea60 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1ea70 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
1ea80 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
1ea90 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
1eaa0 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
1eab0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
1eac0 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
1ead0 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
1eae0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
1eaf0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
1eb00 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
1eb10 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
1eb20 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
1eb30 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
1eb40 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
1eb50 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
1eb60 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
1eb70 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
1eb80 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
1eb90 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
1eba0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
1ebb0 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
1ebc0 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1ebd0 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
1ebe0 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
1ebf0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
1ec00 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
1ec10 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1ec20 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
1ec30 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
1ec40 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
1ec50 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
1ec60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1ec70 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
1ec80 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
1ec90 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
1eca0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
1ecb0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
1ecc0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1ecd0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1ece0 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
1ecf0 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
1ed00 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
1ed10 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1ed20 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
1ed30 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
1ed40 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
1ed50 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
1ed60 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
1ed70 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
1ed80 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1ed90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1eda0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  lloc()]..*/.SQLI
1edb0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c  TE_API void *SQL
1edc0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1edd0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1ede0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1edf0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
1ee00 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1ee10 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  4(sqlite3_uint64
1ee20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1ee30 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
1ee40 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  LL sqlite3_reall
1ee50 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
1ee60 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1ee70 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
1ee80 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1ee90 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  4(void*, sqlite3
1eea0 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  _uint64);.SQLITE
1eeb0 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
1eec0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1eed0 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51  _free(void*);.SQ
1eee0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
1eef0 5f 75 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53  _uint64 SQLITE_S
1ef00 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d  TDCALL sqlite3_m
1ef10 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  size(void*);../*
1ef20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1ef30 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
1ef40 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
1ef50 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
1ef60 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
1ef70 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
1ef80 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
1ef90 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
1efa0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
1efb0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
1efc0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1efd0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
1efe0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
1eff0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
1f000 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1f010 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
1f020 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1f030 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
1f040 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1f050 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1f060 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
1f070 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
1f080 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
1f090 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
1f0a0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1f0b0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1f0c0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1f0d0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
1f0e0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
1f0f0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1f100 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
1f110 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1f120 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
1f130 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
1f140 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1f150 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1f160 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1f170 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1f180 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
1f190 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
1f1a0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
1f1b0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
1f1c0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1f1d0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
1f1e0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
1f1f0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
1f200 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
1f210 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
1f220 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
1f230 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
1f240 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
1f250 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
1f260 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
1f270 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
1f280 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
1f290 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1f2a0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
1f2b0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
1f2c0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
1f2d0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1f2e0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
1f2f0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1f300 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1f310 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1f320 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1f330 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1f340 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1f350 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  eset..*/.SQLITE_
1f360 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
1f370 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  4 SQLITE_STDCALL
1f380 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1f390 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49  used(void);.SQLI
1f3a0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
1f3b0 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43  nt64 SQLITE_STDC
1f3c0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ALL sqlite3_memo
1f3d0 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
1f3e0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
1f3f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
1f400 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
1f410 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
1f420 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
1f430 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
1f440 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
1f450 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
1f460 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
1f470 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
1f480 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
1f490 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
1f4a0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
1f4b0 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
1f4c0 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
1f4d0 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
1f4e0 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
1f4f0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
1f500 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
1f510 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
1f520 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
1f530 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
1f540 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
1f550 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
1f560 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
1f570 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
1f580 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
1f590 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
1f5a0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
1f5b0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
1f5c0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
1f5d0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
1f5e0 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65   ^The P paramete
1f5f0 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  r can be a NULL 
1f600 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1f610 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
1f620 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
1f630 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
1f640 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
1f650 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
1f660 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72  less than one or
1f670 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1f680 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20  for P, then the 
1f690 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65  PRNG is.** seede
1f6a0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
1f6b0 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ss obtained from
1f6c0 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
1f6d0 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68   method of.** th
1f6e0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1f6f0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
1f700 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
1f710 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
1f720 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
1f730 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61  N of 1 or more a
1f740 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c  nd a.** non-NULL
1f750 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75   P then the pseu
1f760 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
1f770 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
1f780 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
1f790 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
1f7a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1f7b0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
1f7c0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c  * method..*/.SQL
1f7d0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
1f7e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1f7f0 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
1f800 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
1f810 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f820 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
1f830 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
1f840 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
1f850 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1f860 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
1f870 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
1f880 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
1f890 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
1f8a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1f8b0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
1f8c0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
1f8d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
1f8e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1f8f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1f900 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
1f910 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
1f920 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
1f930 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1f940 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
1f950 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f960 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
1f970 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1f980 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1f990 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
1f9a0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
1f9b0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
1f9c0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
1f9d0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
1f9e0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
1f9f0 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
1fa00 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
1fa10 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1fa20 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1fa30 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
1fa40 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
1fa50 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
1fa60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fa70 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
1fa80 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1fa90 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
1faa0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
1fab0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
1fac0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
1fad0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
1fae0 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
1faf0 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
1fb00 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
1fb10 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
1fb20 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
1fb30 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
1fb40 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
1fb50 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
1fb60 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
1fb70 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fb80 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1fb90 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
1fba0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
1fbb0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
1fbc0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
1fbd0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
1fbe0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fbf0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1fc00 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1fc10 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
1fc20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1fc30 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1fc40 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
1fc50 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
1fc60 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1fc70 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
1fc80 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
1fc90 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
1fca0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
1fcb0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1fcc0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
1fcd0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1fce0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1fcf0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1fd00 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1fd10 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1fd20 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1fd30 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1fd40 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
1fd50 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
1fd60 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
1fd70 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1fd80 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1fd90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1fda0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1fdb0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
1fdc0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
1fdd0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1fde0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
1fdf0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1fe00 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
1fe10 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1fe20 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
1fe30 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
1fe40 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1fe50 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
1fe60 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
1fe70 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
1fe80 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
1fe90 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
1fea0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1feb0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
1fec0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1fed0 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
1fee0 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
1fef0 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
1ff00 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1ff10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1ff20 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1ff30 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
1ff40 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
1ff50 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1ff60 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1ff70 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
1ff80 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
1ff90 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
1ffa0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
1ffb0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
1ffc0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
1ffd0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1ffe0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
1fff0 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
20000 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
20010 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
20020 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
20030 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
20040 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
20050 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
20060 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
20070 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
20080 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
20090 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
200a0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
200b0 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
200c0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
200d0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
200e0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
200f0 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
20100 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
20110 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
20120 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
20130 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
20140 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
20150 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
20160 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
20170 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
20180 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
20190 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
201a0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
201b0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
201c0 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
201d0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
201e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
201f0 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
20200 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
20210 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
20220 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
20230 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
20240 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
20250 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
20260 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
20270 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
20280 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
20290 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
202a0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
202b0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
202c0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
202d0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
202e0 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
202f0 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
20300 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
20310 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
20320 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
20330 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
20340 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
20350 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
20360 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
20370 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
20380 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
20390 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
203a0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
203b0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
203c0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
203d0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
203e0 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
203f0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
20400 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
20410 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
20420 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
20430 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
20440 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
20450 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
20460 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
20470 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
20480 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
20490 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
204a0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
204b0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
204c0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
204d0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
204e0 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
204f0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
20500 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
20510 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
20520 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
20530 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
20540 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
20550 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
20560 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
20570 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
20580 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
20590 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
205a0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
205b0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
205c0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
205d0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
205e0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
205f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
20600 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20610 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
20620 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
20630 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
20640 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20650 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
20660 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20670 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
20680 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
20690 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
206a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
206b0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
206c0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
206d0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
206e0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
206f0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
20700 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
20710 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
20720 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
20730 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
20740 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
20750 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
20760 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
20770 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
20780 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
20790 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
207a0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
207b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
207c0 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
207d0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
207e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
207f0 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
20800 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
20810 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20820 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
20830 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
20840 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
20850 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
20860 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
20870 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
20880 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
20890 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
208a0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
208b0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
208c0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
208d0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
208e0 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
208f0 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
20900 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
20910 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
20920 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
20930 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
20940 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
20950 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
20960 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53  ema change..*/.S
20970 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
20980 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
20990 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
209a0 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
209b0 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
209c0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
209d0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
209e0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
209f0 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
20a00 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
20a10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20a20 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
20a30 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
20a40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
20a50 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
20a60 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20a70 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
20a80 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
20a90 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
20aa0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
20ab0 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
20ac0 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
20ad0 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
20ae0 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
20af0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
20b00 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
20b10 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20b20 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
20b30 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
20b40 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
20b50 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
20b60 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
20b70 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
20b80 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
20b90 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75  [conflict resolu
20ba0 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65  tion mode].** re
20bb0 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  turned from the 
20bc0 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
20bd0 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
20be0 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
20bf0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
20c00 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
20c10 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
20c20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
20c30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20c40 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
20c50 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
20c60 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
20c70 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
20c80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20c90 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
20ca0 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
20cb0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
20cc0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
20cd0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
20ce0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
20cf0 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
20d00 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
20d10 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
20d20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
20d30 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
20d40 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
20d50 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
20d60 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
20d70 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
20d80 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
20d90 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
20da0 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
20db0 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
20dc0 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
20dd0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20de0 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
20df0 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
20e00 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
20e10 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
20e20 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
20e30 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
20e40 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
20e50 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
20e60 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
20e70 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
20e80 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
20e90 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
20ea0 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
20eb0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
20ec0 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
20ed0 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
20ee0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
20ef0 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
20f00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
20f10 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
20f20 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
20f30 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
20f40 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
20f50 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
20f60 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
20f70 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
20f80 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
20f90 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
20fa0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
20fb0 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
20fc0 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
20fd0 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
20fe0 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
20ff0 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
21000 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
21010 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
21020 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
21030 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
21040 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
21050 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21060 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21070 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
21080 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
21090 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
210a0 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
210b0 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
210c0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
210d0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
210e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
210f0 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
21100 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
21110 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21120 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21130 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21140 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
21150 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
21160 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
21170 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21180 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21190 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
211a0 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
211b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
211c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
211d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
211e0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
211f0 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
21200 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
21210 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21220 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21230 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
21240 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
21250 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
21260 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21280 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
21290 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
212a0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
212b0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
212c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
212d0 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
212e0 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
212f0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
21300 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
21320 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
21330 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
21340 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21350 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21360 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21370 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
21380 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
21390 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
213a0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
213b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
213c0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
213d0 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
213e0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
213f0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21400 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
21410 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
21420 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
21430 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
21440 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21450 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
21460 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
21470 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21480 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21490 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
214a0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
214b0 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
214c0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
214d0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
214e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
214f0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
21500 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
21510 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
21520 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21530 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21540 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
21550 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
21560 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
21570 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21580 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21590 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
215a0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
215b0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
215c0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
215d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
215e0 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
215f0 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
21600 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21610 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21620 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21630 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
21640 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
21650 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
21660 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
21670 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21680 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
21690 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
216a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
216b0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
216c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
216d0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
216e0 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
216f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
21700 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21710 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21720 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
21730 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
21740 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
21750 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21760 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
21770 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
21780 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
21790 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
217a0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
217b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
217c0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
217d0 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
217e0 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
217f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21800 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
21810 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
21820 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
21830 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
21840 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21850 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
21860 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
21870 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
21880 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
21890 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
218a0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
218b0 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
218c0 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
218d0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
218e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
218f0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
21900 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
21910 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
21920 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
21930 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21940 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21950 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
21960 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21970 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
21980 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
21990 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
219a0 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
219b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
219c0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
219d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
219e0 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
219f0 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
21a00 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
21a10 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
21a20 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
21a30 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
21a40 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
21a50 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
21a60 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
21a70 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
21a80 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
21a90 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
21aa0 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
21ab0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21ac0 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20  TE_RECURSIVE    
21ad0 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20          33   /* 
21ae0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21af0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21b00 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
21b10 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
21b20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
21b30 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
21b40 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
21b50 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
21b60 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
21b70 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
21b80 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
21b90 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
21ba0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
21bb0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
21bc0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
21bd0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
21be0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
21bf0 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
21c00 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
21c10 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
21c20 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
21c30 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
21c40 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
21c50 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
21c60 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
21c70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
21c80 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
21c90 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
21ca0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
21cb0 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
21cc0 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
21cd0 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
21ce0 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
21cf0 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
21d00 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
21d10 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
21d20 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
21d30 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
21d40 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
21d50 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
21d60 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
21d70 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
21d80 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
21d90 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
21da0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
21db0 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
21dc0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
21dd0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
21de0 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
21df0 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
21e00 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
21e10 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
21e20 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
21e30 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
21e40 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
21e50 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
21e60 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
21e70 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
21e80 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
21e90 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
21ea0 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
21eb0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
21ec0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
21ed0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
21ee0 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
21ef0 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
21f00 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
21f10 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
21f20 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
21f30 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
21f40 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
21f50 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
21f60 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
21f70 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
21f80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
21f90 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
21fa0 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
21fb0 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
21fc0 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
21fd0 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
21fe0 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
21ff0 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
22000 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
22010 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
22020 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
22030 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
22040 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
22050 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
22060 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
22070 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
22080 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
22090 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
220a0 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
220b0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
220c0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
220d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
220e0 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
220f0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61  CALL sqlite3_tra
22100 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
22110 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
22120 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
22130 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  oid*);.SQLITE_AP
22140 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  I SQLITE_EXPERIM
22150 45 4e 54 41 4c 20 76 6f 69 64 20 2a 53 51 4c 49  ENTAL void *SQLI
22160 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
22170 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
22180 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
22190 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
221a0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
221b0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
221c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
221d0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
221e0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  ss Callbacks.** 
221f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
22200 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
22210 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
22220 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
22230 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
22240 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
22250 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
22260 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
22270 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
22280 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
22290 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
222a0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
222b0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
222c0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
222d0 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
222e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
222f0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
22300 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
22310 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
22320 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
22330 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
22340 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
22350 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
22360 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
22370 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
22380 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
22390 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
223a0 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
223b0 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72  er N is the appr
223c0 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f  oximate number o
223d0 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
223e0 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
223f0 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
22400 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
22410 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
22420 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
22430 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49   callback X.  ^I
22440 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
22450 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72   one then the pr
22460 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65  ogress.** handle
22470 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  r is disabled..*
22480 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
22490 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
224a0 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
224b0 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
224c0 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
224d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
224e0 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
224f0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
22500 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
22510 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
22520 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
22530 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
22540 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
22550 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
22560 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
22570 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
22580 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
22590 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
225a0 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
225b0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
225c0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
225d0 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
225e0 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
225f0 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
22600 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
22610 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
22620 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
22630 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
22640 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
22650 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
22660 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
22670 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
22680 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
22690 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
226a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
226b0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
226c0 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
226d0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
226e0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
226f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
22700 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22710 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
22720 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
22730 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
22740 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
22750 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
22760 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
22770 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
22780 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
22790 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
227a0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
227b0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
227c0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
227d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
227e0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
227f0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
22800 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  n.** CONSTRUCTOR
22810 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
22820 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
22830 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
22840 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
22850 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
22860 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
22870 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
22880 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
22890 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
228a0 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
228b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
228c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
228d0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
228e0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
228f0 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
22900 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
22910 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
22920 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
22930 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
22940 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
22950 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
22960 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
22970 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
22980 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
22990 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
229a0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
229b0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
229c0 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
229d0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
229e0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
229f0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
22a00 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
22a10 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
22a20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
22a30 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
22a40 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
22a50 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
22a60 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
22a70 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
22a80 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
22a90 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
22aa0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
22ab0 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
22ac0 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
22ad0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
22ae0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
22af0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
22b00 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
22b10 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
22b20 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
22b30 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
22b40 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
22b50 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
22b60 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
22b70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
22b80 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c  lt encoding will
22b90 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61   be UTF-8 for da
22ba0 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20  tabases created 
22bb0 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  using.** sqlite3
22bc0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
22bd0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e  e3_open_v2().  ^
22be0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
22bf0 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73  ding for databas
22c00 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73  es.** created us
22c10 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
22c20 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46  16() will be UTF
22c30 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
22c40 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
22c50 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
22c60 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
22c70 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
22c80 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
22c90 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
22ca0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
22cb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
22cc0 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
22cd0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
22ce0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
22cf0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
22d00 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
22d10 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
22d20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
22d30 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
22d40 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
22d50 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
22d60 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
22d70 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
22d80 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
22d90 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
22da0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
22db0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
22dc0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
22dd0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
22de0 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
22df0 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
22e00 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
22e10 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
22e20 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
22e30 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
22e40 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
22e50 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
22e60 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
22e70 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
22e80 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
22e90 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
22ea0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
22eb0 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
22ec0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
22ed0 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
22ee0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
22ef0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
22f00 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
22f10 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
22f20 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
22f30 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
22f40 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
22f50 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
22f60 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
22f70 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
22f80 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
22f90 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
22fa0 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
22fb0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
22fc0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
22fd0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
22fe0 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
22ff0 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
23000 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
23010 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
23020 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
23030 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
23040 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
23050 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
23060 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
23070 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
23080 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
23090 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
230a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
230b0 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
230c0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
230d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
230e0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
230f0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
23100 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
23110 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
23120 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
23130 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
23140 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
23150 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
23160 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
23170 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
23180 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
23190 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
231a0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
231b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
231c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
231d0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
231e0 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
231f0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
23200 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
23210 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
23220 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
23230 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
23240 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
23250 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
23260 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
23270 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
23280 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
23290 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
232a0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
232b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
232c0 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
232d0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
232e0 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
232f0 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
23300 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
23310 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
23320 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
23330 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
23340 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
23350 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
23360 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
23370 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
23380 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
23390 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
233a0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
233b0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
233c0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
233d0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
233e0 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
233f0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
23400 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
23410 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
23420 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
23430 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
23440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
23450 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
23460 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
23470 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
23480 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
23490 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
234a0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
234b0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
234c0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
234d0 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
234e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
234f0 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
23500 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
23510 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23520 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
23530 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
23540 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
23550 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
23560 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
23570 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
23580 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
23590 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
235a0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
235b0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
235c0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
235d0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
235e0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
235f0 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
23600 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23610 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
23620 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
23630 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
23640 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
23650 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
23660 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
23670 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
23680 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
23690 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
236a0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
236b0 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
236c0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
236d0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
236e0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
236f0 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
23700 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
23710 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
23720 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
23730 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
23740 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
23750 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
23760 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
23770 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
23780 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
23790 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
237a0 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
237b0 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
237c0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
237d0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
237e0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
237f0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
23800 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
23810 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
23820 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
23830 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
23840 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
23850 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
23860 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
23870 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
23880 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
23890 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
238a0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
238b0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
238c0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
238d0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
238e0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
238f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
23900 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
23910 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
23920 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
23930 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
23940 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
23950 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
23960 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
23970 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
23980 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
23990 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
239a0 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
239b0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
239c0 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
239d0 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
239e0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
239f0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
23a00 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
23a10 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
23a20 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
23a30 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
23a40 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
23a50 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
23a60 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
23a70 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
23a80 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
23a90 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
23aa0 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
23ab0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
23ac0 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
23ad0 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
23ae0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
23af0 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
23b00 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
23b10 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
23b20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
23b30 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
23b40 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
23b50 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
23b60 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
23b70 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
23b80 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
23b90 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
23ba0 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
23bb0 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
23bc0 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
23bd0 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
23be0 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
23bf0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
23c00 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
23c10 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
23c20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
23c30 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
23c40 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
23c50 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
23c60 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
23c70 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
23c80 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
23c90 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
23ca0 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
23cb0 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
23cc0 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
23cd0 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
23ce0 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
23cf0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
23d00 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
23d10 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
23d20 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
23d30 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
23d40 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
23d50 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
23d60 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
23d70 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
23d80 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
23d90 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
23da0 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
23db0 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
23dc0 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
23dd0 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
23de0 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
23df0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
23e00 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
23e10 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
23e20 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
23e30 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
23e40 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
23e50 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
23e60 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
23e70 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
23e80 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
23e90 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
23ea0 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
23eb0 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77   .** ^(On window
23ec0 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
23ed0 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
23ee0 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
23ef0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
23f00 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
23f10 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  :").)^.**.** [[c
23f20 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
23f30 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
23f40 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
23f50 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
23f60 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
23f70 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
23f80 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
23f90 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
23fa0 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
23fb0 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
23fc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
23fd0 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20   SQLite and its 
23fe0 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d  built-in [VFSes]
23ff0 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
24000 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72  * following quer
24010 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
24020 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
24030 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
24040 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
24050 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
24060 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
24070 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
24080 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
24090 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
240a0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
240b0 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
240c0 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
240d0 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
240e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
240f0 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
24100 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
24110 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
24120 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
24130 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
24140 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
24150 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
24160 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
24170 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
24180 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
24190 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
241a0 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
241b0 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
241c0 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
241d0 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
241e0 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
241f0 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
24200 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
24210 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
24220 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
24230 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
24240 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
24250 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
24260 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
24270 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
24280 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
24290 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
242a0 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
242b0 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
242c0 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
242d0 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
242e0 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
242f0 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
24300 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
24310 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
24320 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
24330 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
24340 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
24350 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
24360 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
24370 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
24380 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
24390 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
243a0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
243b0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
243c0 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
243d0 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
243e0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
243f0 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
24400 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
24410 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
24420 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
24430 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
24440 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
24450 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
24460 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
24470 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
24480 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
24490 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
244a0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
244b0 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
244c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
244d0 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
244e0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
244f0 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
24500 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
24510 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
24520 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
24530 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
24540 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
24550 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
24560 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
24570 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
24580 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
24590 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
245a0 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
245b0 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
245c0 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
245d0 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
245e0 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
245f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
24600 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
24610 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
24620 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
24630 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
24640 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
24650 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
24660 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
24670 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
24680 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
24690 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
246a0 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
246b0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
246c0 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
246d0 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
246e0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
246f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24700 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
24710 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
24720 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
24730 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
24740 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
24750 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
24760 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
24770 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
24780 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
24790 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
247a0 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
247b0 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
247c0 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
247d0 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
247e0 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
247f0 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
24800 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
24810 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
24820 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
24830 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
24840 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a  ACHE flag..**.**
24850 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f    <li> <b>psow</
24860 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61  b>: ^The psow pa
24870 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65  rameter indicate
24880 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  s whether or not
24890 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77   the.**     [pow
248a0 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65  ersafe overwrite
248b0 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20  ] property does 
248c0 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c  or does not appl
248d0 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  y to the.**     
248e0 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e  storage media on
248f0 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62   which the datab
24900 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73  ase file resides
24910 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
24920 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68  >nolock</b>: ^Th
24930 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74  e nolock paramet
24940 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
24950 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a  query parameter.
24960 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20  **     which if 
24970 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c  set disables fil
24980 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c  e locking in rol
24990 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f  lback journal mo
249a0 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20  des.  This.**   
249b0 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20    is useful for 
249c0 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61  accessing a data
249d0 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79  base on a filesy
249e0 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e  stem that does n
249f0 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72  ot.**     suppor
24a00 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74  t locking.  Caut
24a10 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63  ion:  Database c
24a20 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20  orruption might 
24a30 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a  result if two.**
24a40 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f       or more pro
24a50 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20  cesses write to 
24a60 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
24a70 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66  e and any one of
24a80 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72   those.**     pr
24a90 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c  ocesses uses nol
24aa0 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  ock=1..**.**  <l
24ab0 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c  i> <b>immutable<
24ac0 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61  /b>: ^The immuta
24ad0 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ble parameter is
24ae0 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
24af0 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65  .**     paramete
24b00 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  r that indicates
24b10 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
24b20 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65  se file is store
24b30 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64  d on.**     read
24b40 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57  -only media.  ^W
24b50 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73  hen immutable is
24b60 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73   set, SQLite ass
24b70 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
24b80 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69       database fi
24b90 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  le cannot be cha
24ba0 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20  nged, even by a 
24bb0 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67  process with hig
24bc0 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69  her.**     privi
24bd0 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  lege, and so the
24be0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
24bf0 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e  ned read-only an
24c00 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a  d all locking.**
24c10 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20       and change 
24c20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73  detection is dis
24c30 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a  abled.  Caution:
24c40 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d   Setting the imm
24c50 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72  utable.**     pr
24c60 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61  operty on a data
24c70 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64  base file that d
24c80 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e  oes in fact chan
24c90 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a  ge can result.**
24ca0 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63       in incorrec
24cb0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  t query results 
24cc0 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43  and/or [SQLITE_C
24cd0 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a  ORRUPT] errors..
24ce0 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a  **     See also:
24cf0 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
24d00 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20  MMUTABLE]..**   
24d10 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a      .** </ul>.**
24d20 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
24d30 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
24d40 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
24d50 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
24d60 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
24d70 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
24d80 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
24d90 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
24da0 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
24db0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
24dc0 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
24dd0 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
24de0 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
24df0 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
24e00 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
24e10 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
24e20 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
24e30 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
24e40 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
24e50 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
24e60 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
24e70 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
24e80 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
24e90 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
24ea0 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
24eb0 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
24ec0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
24ed0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
24ee0 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
24ef0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
24f00 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
24f10 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
24f20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
24f30 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
24f40 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
24f50 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
24f60 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
24f70 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
24f80 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
24f90 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
24fa0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
24fb0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
24fc0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
24fd0 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
24fe0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
24ff0 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
25000 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
25010 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
25020 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
25030 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
25040 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
25050 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
25060 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
25070 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
25080 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
25090 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
250a0 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
250b0 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
250c0 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
250d0 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
250e0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
250f0 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
25100 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
25110 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
25120 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
25130 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
25140 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
25150 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
25160 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
25170 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
25180 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
25190 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
251a0 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
251b0 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
251c0 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
251d0 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
251e0 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
251f0 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
25200 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
25210 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
25220 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
25230 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
25240 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
25250 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
25260 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
25270 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
25280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
25290 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
252a0 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
252b0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
252c0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
252d0 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20  fs=unix-dotfile 
252e0 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
252f0 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
25300 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
25310 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
25320 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69   VFS "unix-dotfi
25330 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  le".**          
25340 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69  that uses dot-fi
25350 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  les in place of 
25360 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c  posix advisory l
25370 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c  ocking..** <tr><
25380 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
25390 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
253a0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
253b0 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
253c0 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
253d0 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
253e0 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
253f0 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
25400 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
25410 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
25420 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
25430 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
25440 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
25450 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
25460 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
25470 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
25480 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
25490 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
254a0 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
254b0 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
254c0 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
254d0 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
254e0 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
254f0 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
25500 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
25510 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
25520 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
25530 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
25540 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
25550 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
25560 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
25570 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
25580 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
25590 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
255a0 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
255b0 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
255c0 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
255d0 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
255e0 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
255f0 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
25600 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
25610 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
25620 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
25630 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
25640 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
25650 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
25660 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
25670 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
25680 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
25690 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
256a0 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
256b0 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
256c0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
256d0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
256e0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
256f0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
25700 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
25710 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
25720 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
25730 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
25740 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
25750 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
25760 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
25770 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
25780 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
25790 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
257a0 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
257b0 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
257c0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
257d0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
257e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
257f0 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
25800 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
25810 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
25820 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
25830 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
25840 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
25850 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
25860 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
25870 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
25880 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
25890 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  LL sqlite3_open(
258a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
258b0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
258c0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
258d0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
258e0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
258f0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
25900 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
25910 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
25920 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
25930 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  L sqlite3_open16
25940 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
25950 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
25960 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
25970 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
25980 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
25990 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
259a0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
259b0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
259c0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
259d0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ALL sqlite3_open
259e0 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
259f0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
25a00 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
25a10 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
25a20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
25a30 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
25a40 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
25a50 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
25a60 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
25a70 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
25a80 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
25a90 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
25aa0 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
25ab0 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
25ac0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
25ad0 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
25ae0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
25af0 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
25b00 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
25b10 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
25b20 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
25b30 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
25b40 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
25b50 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
25b60 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
25b70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
25b80 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
25b90 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
25ba0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
25bb0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
25bc0 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
25bd0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
25be0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
25bf0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
25c00 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
25c10 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
25c20 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
25c30 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
25c40 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
25c50 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
25c60 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
25c70 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
25c80 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
25c90 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
25ca0 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
25cb0 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
25cc0 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
25cd0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
25ce0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
25cf0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
25d00 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
25d10 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
25d20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
25d30 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
25d40 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
25d50 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
25d60 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
25d70 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
25d80 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
25d90 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
25da0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
25db0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
25dc0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
25dd0 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
25de0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
25df0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
25e00 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
25e10 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
25e20 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
25e30 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
25e40 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
25e50 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
25e60 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
25e70 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
25e80 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
25e90 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
25ea0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
25eb0 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
25ec0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
25ed0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
25ee0 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
25ef0 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
25f00 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
25f10 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
25f20 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
25f30 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
25f40 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
25f50 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
25f60 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
25f70 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
25f80 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
25f90 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
25fa0 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
25fb0 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
25fc0 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
25fd0 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
25fe0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
25ff0 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
26000 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
26010 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
26020 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
26030 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
26040 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
26050 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
26060 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
26070 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
26080 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
26090 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
260a0 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
260b0 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
260c0 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
260d0 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
260e0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
260f0 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
26100 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
26110 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
26120 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
26130 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
26140 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
26150 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
26160 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
26170 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
26180 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
26190 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
261a0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
261b0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
261c0 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
261d0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
261e0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
261f0 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
26200 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
26210 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
26220 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
26230 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
26240 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
26250 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
26260 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
26270 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
26280 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
26290 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
262a0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
262b0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
262c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
262d0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
262e0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75  TDCALL sqlite3_u
262f0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
26300 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
26310 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
26320 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f  zParam);.SQLITE_
26330 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
26340 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75  TDCALL sqlite3_u
26350 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
26360 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
26370 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
26380 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
26390 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
263a0 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45  te3_int64 SQLITE
263b0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
263c0 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
263d0 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
263e0 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
263f0 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
26400 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
26410 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
26420 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
26430 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e3.**.** ^If the
26440 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c   most recent sql
26450 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20  ite3_* API call 
26460 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
26470 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
26480 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c  nnection] D fail
26490 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ed, then the sql
264a0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20  ite3_errcode(D) 
264b0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
264c0 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
264d0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
264e0 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  r [extended resu
264f0 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61  lt code] for tha
26500 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a  t.** API call..*
26510 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  * If the most re
26520 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61  cent API call wa
26530 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a  s successful,.**
26540 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
26550 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
26560 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
26570 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
26580 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
26590 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
265a0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
265b0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
265c0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
265d0 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
265e0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
265f0 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
26600 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
26610 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
26620 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
26630 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
26640 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
26650 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
26660 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
26670 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
26680 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
26690 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
266a0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
266b0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
266c0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
266d0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
266e0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
266f0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
26700 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
26710 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
26720 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
26730 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
26740 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
26750 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
26760 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
26770 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
26780 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
26790 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
267a0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
267b0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
267c0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
267d0 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
267e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
267f0 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
26800 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
26810 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
26820 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
26830 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
26840 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
26850 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
26860 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
26870 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
26880 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
26890 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
268a0 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
268b0 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
268c0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
268d0 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
268e0 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
268f0 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
26900 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
26910 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
26920 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
26930 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
26940 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
26950 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
26960 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
26970 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
26980 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
26990 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
269a0 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
269b0 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
269c0 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
269d0 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
269e0 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
269f0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
26a00 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
26a10 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
26a20 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
26a30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26a40 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
26a50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
26a60 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
26a70 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
26a80 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
26a90 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
26aa0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
26ab0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
26ac0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
26ad0 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
26ae0 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
26af0 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
26b00 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
26b10 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
26b20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
26b30 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
26b40 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
26b50 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
26b60 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
26b70 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
26b80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
26b90 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
26ba0 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
26bb0 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
26bc0 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
26bd0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
26be0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
26bf0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 63  ALL sqlite3_errc
26c00 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
26c10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
26c20 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
26c30 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
26c40 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
26c50 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50   *db);.SQLITE_AP
26c60 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
26c70 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
26c80 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
26c90 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
26ca0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
26cb0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
26cc0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
26cd0 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f  lite3*);.SQLITE_
26ce0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
26cf0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
26d00 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
26d10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
26d20 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
26d30 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
26d40 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
26d50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
26d60 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
26d70 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
26d80 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
26d90 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
26da0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
26db0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
26dc0 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
26dd0 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
26de0 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
26df0 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
26e00 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
26e10 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
26e20 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
26e30 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
26e40 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
26e50 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
26e60 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
26e70 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
26e80 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
26e90 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
26ea0 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
26eb0 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
26ec0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
26ed0 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
26ee0 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
26ef0 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
26f00 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
26f10 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
26f20 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
26f30 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
26f40 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
26f50 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
26f60 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
26f70 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
26f80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
26f90 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
26fa0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
26fb0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
26fc0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
26fd0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
26fe0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
26ff0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
27000 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
27010 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27020 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
27030 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
27040 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
27050 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
27060 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
27070 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
27080 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
27090 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
270a0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
270b0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
270c0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
270d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
270e0 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
270f0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
27100 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
27110 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
27120 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
27130 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
27140 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
27150 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
27160 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
27170 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
27180 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
27190 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
271a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
271b0 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
271c0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
271d0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
271e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
271f0 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
27200 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
27210 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
27220 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
27230 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
27240 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
27250 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
27260 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
27270 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
27280 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
27290 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
272a0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
272b0 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
272c0 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
272d0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
272e0 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
272f0 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
27300 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
27310 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
27320 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
27330 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
27340 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
27350 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
27360 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
27370 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
27380 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
27390 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
273a0 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
273b0 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
273c0 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
273d0 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
273e0 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
273f0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
27400 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
27410 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
27420 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
27430 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
27440 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
27450 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
27460 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
27470 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
27480 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
27490 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
274a0 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
274b0 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
274c0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
274d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
274e0 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
274f0 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
27500 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
27510 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
27520 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
27530 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
27540 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
27550 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
27560 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
27570 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
27580 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
27590 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
275a0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
275b0 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
275c0 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
275d0 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
275e0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
275f0 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
27600 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
27610 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
27620 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
27630 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
27640 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
27650 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
27660 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
27670 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
27680 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
27690 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
276a0 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
276b0 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
276c0 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
276d0 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
276e0 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
276f0 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
27700 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
27710 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
27720 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
27730 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
27740 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
27750 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
27760 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
27770 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
27780 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
27790 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
277a0 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
277b0 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
277c0 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
277d0 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
277e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
277f0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
27800 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
27810 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
27820 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
27830 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
27840 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
27850 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
27860 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
27870 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
27880 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
27890 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
278a0 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
278b0 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
278c0 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
278d0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
278e0 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  leases..*/.SQLIT
278f0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
27900 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
27910 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
27920 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
27930 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
27940 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
27950 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
27960 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
27970 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
27980 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
27990 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
279a0 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
279b0 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
279c0 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
279d0 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
279e0 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
279f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
27a00 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
27a10 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
27a20 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
27a30 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
27a40 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
27a50 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
27a60 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
27a70 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
27a80 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
27a90 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
27aa0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
27ab0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
27ac0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
27ad0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
27ae0 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
27af0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
27b00 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
27b10 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
27b20 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
27b30 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
27b40 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
27b50 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
27b60 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
27b70 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
27b80 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
27b90 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
27ba0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
27bb0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
27bc0 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
27bd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
27be0 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
27bf0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
27c00 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
27c10 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
27c20 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
27c30 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
27c40 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
27c50 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
27c60 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
27c70 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
27c80 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
27c90 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
27ca0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
27cb0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
27cc0 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
27cd0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
27ce0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
27cf0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
27d00 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
27d10 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
27d20 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
27d30 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
27d40 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
27d50 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
27d60 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
27d70 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
27d80 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
27d90 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
27da0 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
27db0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
27dc0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
27dd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
27de0 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
27df0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
27e00 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
27e10 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
27e20 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
27e30 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
27e40 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
27e50 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
27e60 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
27e70 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
27e80 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
27e90 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
27ea0 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
27eb0 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
27ec0 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
27ed0 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
27ee0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
27ef0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
27f00 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
27f10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
27f20 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
27f30 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
27f40 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
27f50 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
27f60 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
27f70 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
27f80 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
27f90 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
27fa0 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
27fb0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
27fc0 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
27fd0 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
27fe0 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
27ff0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
28000 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
28010 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
28020 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28030 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
28040 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
28050 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
28060 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
28070 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
28080 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
28090 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
280a0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
280b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
280c0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
280d0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
280e0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
280f0 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
28100 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
28110 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
28120 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
28130 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
28140 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
28150 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
28160 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
28170 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
28180 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
28190 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
281a0 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
281b0 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
281c0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
281d0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
281e0 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d  WORKER_THREADS]]
281f0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
28200 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
28210 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  DS</dt>.** <dd>T
28220 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
28230 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77  r of auxiliary w
28240 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68  orker threads th
28250 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  at a single.** [
28260 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28270 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f  nt] may start.</
28280 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
28290 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
282a0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
282b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
282c0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
282d0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
282e0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
282f0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
28300 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
28310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28320 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
28330 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
28340 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
28350 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
28360 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
28370 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
28380 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
28390 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
283a0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
283b0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
283c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
283d0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
283e0 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
283f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
28400 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
28410 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
28420 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
28430 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
28440 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
28450 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
28460 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
28470 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
28480 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
28490 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
284a0 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
284b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
284c0 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
284d0 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f             11../
284e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
284f0 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
28500 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
28510 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
28520 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
28530 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
28540 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  e3.** CONSTRUCTO
28550 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
28560 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
28570 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
28580 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
28590 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
285a0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
285b0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
285c0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
285d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
285e0 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
285f0 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
28600 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
28610 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
28620 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
28630 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
28640 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
28650 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
28660 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
28670 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
28680 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28690 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
286a0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
286b0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
286c0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
286d0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
286e0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
286f0 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
28700 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
28710 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
28720 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
28730 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
28740 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
28750 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
28760 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
28770 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
28780 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
28790 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
287a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
287b0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
287c0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
287d0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
287e0 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
287f0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
28800 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70  . ^If nByte is p
28810 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74  ositive, then it
28820 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
28830 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20  r of bytes read 
28840 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20  from zSql.  ^If 
28850 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74  nByte is zero, t
28860 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a  hen no prepared.
28870 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ** statement is 
28880 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66  generated..** If
28890 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
288a0 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  s that the suppl
288b0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
288c0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
288d0 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61  en.** there is a
288e0 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e   small performan
288f0 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
28900 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
28910 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
28920 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
28930 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
28940 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
28950 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
28960 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
28970 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ator..**.** ^If 
28980 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
28990 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
289a0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
289b0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
289c0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
289d0 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
289e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
289f0 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
28a00 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
28a10 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
28a20 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
28a30 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
28a40 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
28a50 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
28a60 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
28a70 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
28a80 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
28a90 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
28aa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28ab0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
28ac0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
28ad0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
28ae0 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
28af0 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
28b00 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
28b10 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
28b20 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
28b30 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
28b40 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
28b50 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
28b60 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
28b70 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
28b80 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
28b90 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
28ba0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
28bb0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
28bc0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
28bd0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
28be0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
28bf0 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
28c00 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
28c10 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
28c20 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
28c30 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
28c40 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
28c50 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
28c60 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
28c70 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
28c80 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
28c90 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
28ca0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
28cb0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
28cc0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
28cd0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
28ce0 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
28cf0 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
28d00 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
28d10 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
28d20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
28d30 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
28d40 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
28d50 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
28d60 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
28d70 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
28d80 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
28d90 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
28da0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
28db0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
28dc0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
28dd0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
28de0 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
28df0 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
28e00 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
28e10 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
28e20 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
28e30 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
28e40 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
28e50 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
28e60 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
28e70 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
28e80 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
28e90 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
28ea0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
28eb0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
28ec0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
28ed0 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
28ee0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
28ef0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
28f00 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
28f10 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
28f20 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
28f30 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
28f40 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
28f50 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
28f60 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
28f70 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
28f80 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
28f90 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
28fa0 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
28fb0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
28fc0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
28fd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
28fe0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
28ff0 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
29000 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
29010 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
29020 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
29030 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
29040 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
29050 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
29060 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
29070 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
29080 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
29090 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
290a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
290b0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
290c0 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
290d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
290e0 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
290f0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
29100 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
29110 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
29120 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
29130 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
29140 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
29150 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
29160 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
29170 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
29180 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
29190 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
291a0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
291b0 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
291c0 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
291d0 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
291e0 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
291f0 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
29200 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
29210 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
29220 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
29230 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
29240 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
29250 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
29260 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
29270 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
29280 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
29290 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
292a0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
292b0 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
292c0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
292d0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
292e0 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
292f0 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
29300 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
29310 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
29320 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
29330 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
29340 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
29350 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
29360 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
29370 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
29380 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
29390 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
293a0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
293b0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
293c0 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
293d0 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
293e0 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
293f0 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
29400 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
29410 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
29420 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
29430 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
29440 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
29450 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  L sqlite3_prepar
29460 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
29470 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
29480 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
29490 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
294a0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
294b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
294c0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
294d0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
294e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
294f0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
29500 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
29510 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
29520 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
29530 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
29540 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
29550 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
29560 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
29570 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
29580 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
29590 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
295a0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
295b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
295c0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
295d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
295e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
295f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
29600 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
29610 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
29620 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
29630 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
29640 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
29650 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
29660 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
29670 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
29680 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
29690 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
296a0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
296b0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
296c0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
296d0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
296e0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
296f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29700 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
29710 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29720 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
29730 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
29740 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
29750 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
29760 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
29770 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
29780 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
29790 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
297a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
297b0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
297c0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
297d0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
297e0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
297f0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
29800 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
29810 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
29820 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
29830 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
29840 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
29850 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29860 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
29870 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29880 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
29890 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
298a0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
298b0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
298c0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
298d0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
298e0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
298f0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
29900 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
29910 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
29920 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
29930 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
29940 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
29950 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
29960 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
29970 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
29980 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
29990 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
299a0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
299b0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
299c0 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
299d0 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
299e0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
299f0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  _stmt.**.** ^Thi
29a00 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
29a10 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
29a20 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
29a30 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
29a40 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
29a50 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
29a60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29a70 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
29a80 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
29a90 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
29aa0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
29ab0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
29ac0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
29ad0 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  2()]..*/.SQLITE_
29ae0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
29af0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
29b00 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
29b10 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
29b20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29b30 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
29b40 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
29b50 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
29b60 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ase.** METHOD: s
29b70 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
29b80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
29b90 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
29ba0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29bb0 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
29bc0 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
29bd0 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
29be0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
29bf0 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
29c00 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
29c10 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
29c20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
29c30 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
29c40 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29c50 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
29c60 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
29c70 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
29c80 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
29c90 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
29ca0 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
29cb0 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
29cc0 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
29cd0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
29ce0 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
29cf0 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
29d00 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
29d10 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
29d20 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
29d30 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
29d40 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
29d50 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
29d60 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
29d70 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
29d80 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
29d90 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
29da0 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
29db0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
29dc0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
29dd0 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
29de0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
29df0 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
29e00 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
29e10 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
29e20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
29e30 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
29e40 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
29e50 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
29e60 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
29e70 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
29e80 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
29e90 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
29ea0 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
29eb0 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
29ec0 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
29ed0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
29ee0 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
29ef0 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
29f00 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
29f10 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
29f20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
29f30 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
29f40 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
29f50 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
29f60 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
29f70 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
29f80 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
29f90 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
29fa0 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
29fb0 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
29fc0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
29fd0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
29fe0 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
29ff0 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
2a000 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
2a010 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
2a020 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
2a030 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
2a040 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
2a050 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
2a060 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2a070 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
2a080 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45   disk..*/.SQLITE
2a090 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2a0a0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2a0b0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
2a0c0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2a0d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2a0e0 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
2a0f0 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
2a100 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
2a110 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Reset.** METHOD:
2a120 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2a130 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a140 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e  _stmt_busy(S) in
2a150 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2a160 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
2a170 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  if the.** [prepa
2a180 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2a190 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65   has been steppe
2a1a0 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  d at least once 
2a1b0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
2a1c0 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20  e3_step(S)] but 
2a1d0 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20  has neither run 
2a1e0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72  to completion (r
2a1f0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
2a200 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73  TE_DONE] from [s
2a210 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29  qlite3_step(S)])
2a220 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73   nor.** been res
2a230 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  et using [sqlite
2a240 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54  3_reset(S)].  ^T
2a250 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2a260 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72  busy(S).** inter
2a270 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c  face returns fal
2a280 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c  se if S is a NUL
2a290 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53  L pointer.  If S
2a2a0 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55   is not a .** NU
2a2b0 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69  LL pointer and i
2a2c0 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20  s not a pointer 
2a2d0 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70  to a valid [prep
2a2e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2a2f0 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20  ** object, then 
2a300 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2a310 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2a320 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
2a330 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  le..**.** This i
2a340 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
2a350 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74  used in combinat
2a360 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  ion [sqlite3_nex
2a370 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20  t_stmt()].** to 
2a380 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61  locate all prepa
2a390 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
2a3a0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
2a3b0 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f   database .** co
2a3c0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72  nnection that ar
2a3d0 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69  e in need of bei
2a3e0 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20  ng reset.  This 
2a3f0 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20  can be used,.** 
2a400 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  for example, in 
2a410 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69  diagnostic routi
2a420 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f  nes to search fo
2a430 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73  r prepared .** s
2a440 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61  tatements that a
2a450 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61  re holding a tra
2a460 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a  nsaction open..*
2a470 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2a480 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2a490 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2a4a0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
2a4b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a4c0 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
2a4d0 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
2a4e0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
2a4f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2a500 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
2a510 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2a520 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
2a530 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
2a540 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2a550 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
2a560 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
2a570 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
2a580 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
2a590 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
2a5a0 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
2a5b0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
2a5c0 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
2a5d0 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
2a5e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2a5f0 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
2a600 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
2a610 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
2a620 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
2a630 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
2a640 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2a650 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
2a660 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
2a670 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
2a680 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
2a690 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
2a6a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2a6b0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
2a6c0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
2a6d0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
2a6e0 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
2a6f0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2a700 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
2a710 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
2a720 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
2a730 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
2a740 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
2a750 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
2a760 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
2a770 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2a780 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20  _value.  The.** 
2a790 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
2a7a0 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  up()] interface 
2a7b0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
2a7c0 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a  onstruct a new .
2a7d0 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  ** protected sql
2a7e0 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20  ite3_value from 
2a7f0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2a800 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2a810 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
2a820 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
2a830 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
2a840 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
2a850 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
2a860 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
2a870 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
2a880 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
2a890 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2a8a0 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
2a8b0 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
2a8c0 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
2a8d0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2a8e0 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
2a8f0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
2a900 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
2a910 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
2a920 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
2a930 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
2a940 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
2a950 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
2a960 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
2a970 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
2a980 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
2a990 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
2a9a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2a9b0 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
2a9c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
2a9d0 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
2a9e0 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
2a9f0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2aa00 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2aa10 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2aa20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2aa30 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
2aa40 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
2aa50 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
2aa60 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
2aa70 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
2aa80 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
2aa90 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
2aaa0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
2aab0 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
2aac0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2aad0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2aae0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2aaf0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2ab00 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
2ab10 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
2ab20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2ab30 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2ab40 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
2ab50 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
2ab60 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
2ab70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2ab80 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2ab90 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2aba0 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
2abb0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
2abc0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2abd0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2abe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2abf0 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
2ac00 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
2ac10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2ac20 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
2ac30 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
2ac40 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
2ac50 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
2ac60 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
2ac70 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
2ac80 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2ac90 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2aca0 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
2acb0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
2acc0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
2acd0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2ace0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
2acf0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2ad00 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
2ad10 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
2ad20 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
2ad30 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
2ad40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
2ad50 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
2ad60 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
2ad70 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
2ad80 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
2ad90 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
2ada0 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
2adb0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
2adc0 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
2add0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
2ade0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
2adf0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2ae00 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
2ae10 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2ae20 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2ae30 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2ae40 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
2ae50 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
2ae60 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
2ae70 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2ae80 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
2ae90 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
2aea0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2aeb0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
2aec0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
2aed0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
2aee0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2aef0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
2af00 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
2af10 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
2af20 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2af30 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
2af40 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
2af50 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
2af60 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
2af70 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
2af80 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
2af90 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
2afa0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
2afb0 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
2afc0 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
2afd0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
2afe0 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
2aff0 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
2b000 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
2b010 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
2b020 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44  nding}.** METHOD
2b030 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2b040 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
2b050 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
2b060 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
2b070 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2b080 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
2b090 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
2b0a0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
2b0b0 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
2b0c0 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
2b0d0 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
2b0e0 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
2b0f0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
2b100 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
2b110 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
2b120 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
2b130 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
2b140 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
2b150 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
2b160 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
2b170 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
2b180 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
2b190 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
2b1a0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
2b1b0 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
2b1c0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
2b1d0 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
2b1e0 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
2b1f0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
2b200 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
2b210 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
2b220 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
2b230 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2b240 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
2b250 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
2b260 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2b270 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
2b280 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2b290 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
2b2a0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
2b2b0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2b2c0 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
2b2d0 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
2b2e0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
2b2f0 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
2b300 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2b310 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2b320 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
2b330 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
2b340 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
2b350 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
2b360 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2b370 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
2b380 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
2b390 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
2b3a0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
2b3b0 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
2b3c0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
2b3d0 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
2b3e0 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
2b3f0 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
2b400 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
2b410 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
2b420 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
2b430 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
2b440 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
2b450 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2b460 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
2b470 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
2b480 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
2b490 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
2b4a0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
2b4b0 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
2b4c0 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
2b4d0 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
2b4e0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2b4f0 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
2b500 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2b510 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
2b520 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
2b530 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
2b540 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2b550 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
2b560 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
2b570 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
2b580 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2b590 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2b5a0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2b5b0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2b5c0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
2b5d0 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
2b5e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
2b5f0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2b600 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
2b610 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
2b620 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
2b630 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
2b640 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
2b650 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
2b660 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
2b670 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2b680 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
2b690 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2b6a0 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
2b6b0 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
2b6c0 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
2b6d0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2b6e0 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
2b6f0 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
2b700 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
2b710 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
2b720 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
2b730 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2b740 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2b750 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2b760 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
2b770 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2b780 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
2b790 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
2b7a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2b7b0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
2b7c0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
2b7d0 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
2b7e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2b7f0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
2b800 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
2b810 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
2b820 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2b830 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
2b840 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
2b850 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
2b860 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
2b870 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
2b880 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2b890 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
2b8a0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2b8b0 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
2b8c0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
2b8d0 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
2b8e0 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
2b8f0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
2b900 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
2b910 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
2b920 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
2b930 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
2b940 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
2b950 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
2b960 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
2b970 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
2b980 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2b990 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
2b9a0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
2b9b0 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
2b9c0 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
2b9d0 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
2b9e0 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
2b9f0 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
2ba00 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
2ba10 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
2ba20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
2ba30 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
2ba40 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
2ba50 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
2ba60 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
2ba70 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
2ba80 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2ba90 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
2baa0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
2bab0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2bac0 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
2bad0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
2bae0 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
2baf0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
2bb00 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
2bb10 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
2bb20 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
2bb30 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2bb40 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
2bb50 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
2bb60 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
2bb70 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
2bb80 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
2bb90 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
2bba0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
2bbb0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2bbc0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
2bbd0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
2bbe0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2bbf0 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
2bc00 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
2bc10 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
2bc20 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
2bc30 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
2bc40 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
2bc50 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
2bc60 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2bc70 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
2bc80 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
2bc90 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2bca0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2bcb0 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
2bcc0 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
2bcd0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2bce0 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
2bcf0 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
2bd00 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
2bd10 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
2bd20 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
2bd30 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
2bd40 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
2bd50 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
2bd60 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2bd70 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2bd80 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
2bd90 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
2bda0 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
2bdb0 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
2bdc0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2bdd0 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
2bde0 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
2bdf0 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
2be00 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
2be10 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
2be20 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2be30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2be40 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2be50 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
2be60 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
2be70 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
2be80 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
2be90 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
2bea0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
2beb0 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
2bec0 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
2bed0 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
2bee0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
2bef0 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
2bf00 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
2bf10 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
2bf20 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
2bf30 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
2bf40 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
2bf50 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
2bf60 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2bf70 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
2bf80 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
2bf90 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
2bfa0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
2bfb0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
2bfc0 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
2bfd0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2bfe0 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
2bff0 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
2c000 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2c010 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
2c020 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
2c030 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
2c040 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c050 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
2c060 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
2c070 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
2c080 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2c090 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
2c0a0 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
2c0b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2c0c0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
2c0d0 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
2c0e0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2c0f0 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
2c100 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
2c110 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
2c120 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c130 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
2c140 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
2c150 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
2c160 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
2c170 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
2c180 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
2c190 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
2c1a0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
2c1b0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
2c1c0 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
2c1d0 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
2c1e0 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
2c1f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c200 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
2c210 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2c220 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
2c230 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
2c240 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
2c250 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
2c260 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42  ** ^[SQLITE_TOOB
2c270 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  IG] might be ret
2c280 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a  urned if the siz
2c290 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72  e of a string or
2c2a0 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73   BLOB.** exceeds
2c2b0 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20   limits imposed 
2c2c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
2c2d0 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
2c2e0 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20  _LENGTH]) or.** 
2c2f0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47  [SQLITE_MAX_LENG
2c300 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  TH]..** ^[SQLITE
2c310 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
2c320 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
2c330 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
2c340 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
2c350 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
2c360 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
2c370 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
2c380 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2c390 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2c3a0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2c3b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2c3c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2c3d0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2c3e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2c3f0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
2c400 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2c410 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2c420 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
2c430 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c440 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2c450 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
2c460 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
2c470 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2c480 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2c490 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  d_blob64(sqlite3
2c4a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2c4b0 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  st void*, sqlite
2c4c0 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2c4d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c4e0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
2c4f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2c500 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2c510 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
2c520 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2c530 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
2c540 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2c550 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2c560 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2c570 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c580 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  int, int);.SQLIT
2c590 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2c5a0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2c5b0 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
2c5c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2c5d0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2c5e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2c5f0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2c600 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2c610 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c620 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2c630 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2c640 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2c650 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
2c660 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  t*,int,const cha
2c670 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  r*,int,void(*)(v
2c680 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2c690 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2c6a0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2c6b0 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
2c6c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2c6d0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2c6e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2c6f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2c700 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2c710 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2c720 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2c730 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
2c740 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  r*, sqlite3_uint
2c750 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
2c760 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2c770 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73  d(*)(void*), uns
2c780 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64  igned char encod
2c790 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ing);.SQLITE_API
2c7a0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2c7b0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2c7c0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2c7d0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2c7e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
2c7f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2c800 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2c810 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2c820 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
2c830 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
2c840 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2c850 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2c860 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2c870 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  oblob64(sqlite3_
2c880 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
2c890 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a  te3_uint64);../*
2c8a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2c8b0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
2c8c0 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44  meters.** METHOD
2c8d0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2c8e0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
2c8f0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
2c900 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
2c910 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
2c920 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
2c930 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c940 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
2c950 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
2c960 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
2c970 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
2c980 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
2c990 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
2c9a0 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
2c9b0 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
2c9c0 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
2c9d0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
2c9e0 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
2c9f0 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
2ca00 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
2ca10 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
2ca20 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
2ca30 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2ca40 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
2ca50 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
2ca60 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
2ca70 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
2ca80 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
2ca90 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
2caa0 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
2cab0 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
2cac0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
2cad0 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
2cae0 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
2caf0 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
2cb00 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
2cb10 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2cb20 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2cb30 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2cb40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2cb50 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
2cb60 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2cb70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2cb80 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2cb90 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2cba0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2cbb0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2cbc0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2cbd0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2cbe0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
2cbf0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
2cc00 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2cc10 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2cc20 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2cc30 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
2cc40 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
2cc50 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
2cc60 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
2cc70 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
2cc80 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2cc90 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2cca0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
2ccb0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
2ccc0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2ccd0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2cce0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
2ccf0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
2cd00 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
2cd10 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2cd20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
2cd30 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
2cd40 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2cd50 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
2cd60 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
2cd70 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
2cd80 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
2cd90 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
2cda0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2cdb0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
2cdc0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
2cdd0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
2cde0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
2cdf0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
2ce00 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
2ce10 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
2ce20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2ce30 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
2ce40 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2ce50 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
2ce60 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
2ce70 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2ce80 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
2ce90 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
2cea0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
2ceb0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2cec0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2ced0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
2cee0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
2cef0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
2cf00 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
2cf10 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
2cf20 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
2cf30 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
2cf40 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2cf50 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2cf60 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2cf70 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2cf80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2cf90 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2cfa0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2cfb0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2cfc0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2cfd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2cfe0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2cff0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
2d000 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
2d010 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2d020 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2d030 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
2d040 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
2d050 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
2d060 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
2d070 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
2d080 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Name.** METHOD: 
2d090 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2d0a0 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
2d0b0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
2d0c0 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
2d0d0 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
2d0e0 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
2d0f0 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
2d100 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
2d110 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
2d120 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2d130 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2d140 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
2d150 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
2d160 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
2d170 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
2d180 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
2d190 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
2d1a0 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
2d1b0 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
2d1c0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
2d1d0 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
2d1e0 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
2d1f0 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
2d200 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2d210 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2d220 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2d230 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2d240 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2d250 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2d260 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2d270 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2d280 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2d290 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  ame()]..*/.SQLIT
2d2a0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2d2b0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d2c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2d2d0 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
2d2e0 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
2d2f0 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
2d300 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2d310 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
2d320 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2d330 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
2d340 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2d350 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
2d360 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
2d370 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
2d380 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
2d390 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
2d3a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2d3b0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
2d3c0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2d3d0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
2d3e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
2d3f0 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
2d400 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
2d410 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  LL..*/.SQLITE_AP
2d420 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2d430 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 65  CALL sqlite3_cle
2d440 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
2d450 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2d460 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2d470 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
2d480 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2d490 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2d4a0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
2d4b0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
2d4c0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2d4d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
2d4e0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
2d4f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d500 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
2d510 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2d520 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
2d530 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
2d540 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
2d550 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
2d560 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
2d570 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
2d580 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
2d590 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c  _count()].*/.SQL
2d5a0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2d5b0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2d5c0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2d5d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2d5e0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2d5f0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
2d600 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
2d610 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
2d620 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2d630 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2d640 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
2d650 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
2d660 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
2d670 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
2d680 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2d690 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2d6a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2d6b0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
2d6c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d6d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2d6e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2d6f0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2d700 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2d710 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
2d720 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2d730 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2d740 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
2d750 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
2d760 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2d770 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2d780 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
2d790 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
2d7a0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2d7b0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
2d7c0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
2d7d0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
2d7e0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
2d7f0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
2d800 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
2d810 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
2d820 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
2d830 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
2d840 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d850 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
2d860 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
2d870 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2d880 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2d890 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2d8a0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2d8b0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2d8c0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2d8d0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2d8e0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2d8f0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
2d900 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
2d910 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2d920 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
2d930 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
2d940 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
2d950 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
2d960 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
2d970 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
2d980 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
2d990 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
2d9a0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
2d9b0 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
2d9c0 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
2d9d0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
2d9e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2d9f0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2da00 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
2da10 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
2da20 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2da30 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
2da40 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
2da50 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
2da60 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
2da70 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
2da80 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
2da90 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
2daa0 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
2dab0 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
2dac0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
2dad0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
2dae0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
2daf0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2db00 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2db10 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2db20 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
2db30 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2db40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2db50 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
2db60 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2db70 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
2db80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2db90 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
2dba0 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
2dbb0 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
2dbc0 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
2dbd0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2dbe0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2dbf0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
2dc00 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
2dc10 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
2dc20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
2dc30 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
2dc40 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
2dc50 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
2dc60 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
2dc70 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
2dc80 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
2dc90 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2dca0 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
2dcb0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
2dcc0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
2dcd0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
2dce0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2dcf0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
2dd00 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
2dd10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
2dd20 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
2dd30 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2dd40 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
2dd50 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
2dd60 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
2dd70 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
2dd80 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
2dd90 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
2dda0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
2ddb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ddc0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
2ddd0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
2dde0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2ddf0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2de00 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2de10 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2de20 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2de30 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2de40 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2de50 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2de60 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2de70 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
2de80 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
2de90 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
2dea0 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
2deb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
2dec0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
2ded0 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
2dee0 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
2def0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
2df00 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
2df10 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
2df20 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2df30 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
2df40 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2df50 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2df60 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2df70 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2df80 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
2df90 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
2dfa0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
2dfb0 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
2dfc0 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
2dfd0 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
2dfe0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
2dff0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
2e000 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
2e010 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
2e020 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
2e030 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2e040 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
2e050 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
2e060 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
2e070 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
2e080 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
2e090 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
2e0a0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
2e0b0 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
2e0c0 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
2e0d0 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
2e0e0 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
2e0f0 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
2e100 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
2e110 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
2e120 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2e130 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2e140 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
2e150 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
2e160 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
2e170 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
2e180 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
2e190 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
2e1a0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
2e1b0 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
2e1c0 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
2e1d0 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
2e1e0 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
2e1f0 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
2e200 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
2e210 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
2e220 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
2e230 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2e240 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2e250 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2e260 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2e270 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2e280 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2e290 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
2e2a0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2e2b0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2e2c0 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
2e2d0 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
2e2e0 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
2e2f0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
2e300 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
2e310 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2e320 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
2e330 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2e340 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2e350 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2e360 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
2e370 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2e380 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
2e390 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
2e3a0 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
2e3b0 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
2e3c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
2e3d0 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
2e3e0 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
2e3f0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
2e400 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2e410 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
2e420 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
2e430 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2e440 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2e450 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
2e460 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2e470 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2e480 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
2e490 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2e4a0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2e4b0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2e4c0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2e4d0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
2e4e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2e4f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2e500 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2e510 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2e520 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2e530 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2e540 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e550 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
2e560 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2e570 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2e580 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2e590 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2e5a0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2e5b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2e5c0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2e5d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
2e5e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2e5f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2e600 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2e610 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2e620 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2e630 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
2e640 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
2e650 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2e660 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2e670 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
2e680 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
2e690 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2e6a0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
2e6b0 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
2e6c0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
2e6d0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
2e6e0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
2e6f0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
2e700 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
2e710 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
2e720 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
2e730 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2e740 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
2e750 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
2e760 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
2e770 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
2e780 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
2e790 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2e7a0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
2e7b0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
2e7c0 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
2e7d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2e7e0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
2e7f0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2e800 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
2e810 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
2e820 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2e830 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
2e840 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
2e850 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
2e860 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
2e870 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
2e880 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
2e890 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
2e8a0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
2e8b0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
2e8c0 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
2e8d0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
2e8e0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
2e8f0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
2e900 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
2e910 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
2e920 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
2e930 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
2e940 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
2e950 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
2e960 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
2e970 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
2e980 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
2e990 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
2e9a0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
2e9b0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
2e9c0 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
2e9d0 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
2e9e0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
2e9f0 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
2ea00 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
2ea10 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
2ea20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
2ea30 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
2ea40 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
2ea50 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
2ea60 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
2ea70 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
2ea80 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
2ea90 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
2eaa0 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
2eab0 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
2eac0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2ead0 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
2eae0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2eaf0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2eb00 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
2eb10 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2eb20 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
2eb30 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2eb40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
2eb50 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
2eb60 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2eb70 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
2eb80 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
2eb90 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
2eba0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2ebb0 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
2ebc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ebd0 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
2ebe0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
2ebf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2ec00 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2ec10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2ec20 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2ec30 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2ec40 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
2ec50 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
2ec60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ec70 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
2ec80 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
2ec90 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
2eca0 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
2ecb0 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
2ecc0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
2ecd0 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
2ece0 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
2ecf0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
2ed00 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
2ed10 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
2ed20 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
2ed30 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
2ed40 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
2ed50 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
2ed60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2ed70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2ed80 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
2ed90 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
2eda0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
2edb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2edc0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2edd0 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
2ede0 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
2edf0 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
2ee00 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2ee10 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
2ee20 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
2ee30 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2ee40 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
2ee50 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
2ee60 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
2ee70 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2ee80 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2ee90 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
2eea0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
2eeb0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
2eec0 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
2eed0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2eee0 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
2eef0 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
2ef00 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
2ef10 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
2ef20 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
2ef30 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
2ef40 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
2ef50 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
2ef60 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
2ef70 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
2ef80 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
2ef90 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
2efa0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
2efb0 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
2efc0 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
2efd0 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
2efe0 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
2eff0 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
2f000 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
2f010 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
2f020 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
2f030 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
2f040 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
2f050 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
2f060 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
2f070 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
2f080 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
2f090 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
2f0a0 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
2f0b0 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
2f0c0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
2f0d0 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
2f0e0 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
2f0f0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
2f100 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
2f110 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
2f120 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
2f130 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
2f140 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
2f150 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
2f160 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
2f170 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
2f180 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
2f190 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
2f1a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
2f1b0 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
2f1c0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
2f1d0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2f1e0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
2f1f0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2f200 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
2f210 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
2f220 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
2f230 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
2f240 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
2f250 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
2f260 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
2f270 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
2f280 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
2f290 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
2f2a0 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
2f2b0 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
2f2c0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
2f2d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
2f2e0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
2f2f0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
2f300 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
2f310 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
2f320 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
2f330 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
2f340 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
2f350 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
2f360 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
2f370 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
2f380 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
2f390 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
2f3a0 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
2f3b0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
2f3c0 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
2f3d0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
2f3e0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
2f3f0 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
2f400 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
2f410 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2f420 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
2f430 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
2f440 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
2f450 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
2f460 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
2f470 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
2f480 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
2f490 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2f4a0 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
2f4b0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2f4c0 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
2f4d0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2f4e0 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
2f4f0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
2f500 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
2f510 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
2f520 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
2f530 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2f540 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2f550 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
2f560 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
2f570 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
2f580 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
2f590 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
2f5a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2f5b0 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
2f5c0 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
2f5d0 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
2f5e0 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
2f5f0 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
2f600 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
2f610 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
2f620 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2f630 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
2f640 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
2f650 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
2f660 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2f670 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
2f680 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
2f690 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
2f6a0 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
2f6b0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
2f6c0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2f6d0 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
2f6e0 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
2f6f0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
2f700 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
2f710 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
2f720 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
2f730 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
2f740 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
2f750 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
2f760 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
2f770 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
2f780 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
2f790 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
2f7a0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
2f7b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
2f7c0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2f7d0 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
2f7e0 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
2f7f0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
2f800 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
2f810 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
2f820 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33   after version 3
2f830 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33  .6.23.1, sqlite3
2f840 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
2f850 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2f860 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
2f870 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
2f880 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
2f890 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
2f8a0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
2f8b0 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
2f8c0 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
2f8d0 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
2f8e0 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
2f8f0 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
2f900 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
2f910 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
2f920 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
2f930 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
2f940 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
2f950 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
2f960 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
2f970 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
2f980 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
2f990 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
2f9a0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
2f9b0 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
2f9c0 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
2f9d0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2f9e0 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
2f9f0 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
2fa00 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
2fa10 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
2fa20 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
2fa30 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
2fa40 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
2fa50 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
2fa60 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
2fa70 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
2fa80 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
2fa90 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
2faa0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2fab0 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
2fac0 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
2fad0 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
2fae0 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
2faf0 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
2fb00 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
2fb10 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
2fb20 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
2fb30 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
2fb40 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
2fb50 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
2fb60 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
2fb70 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
2fb80 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
2fb90 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
2fba0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
2fbb0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2fbc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2fbd0 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
2fbe0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
2fbf0 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
2fc00 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
2fc10 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2fc20 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
2fc30 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
2fc40 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
2fc50 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
2fc60 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
2fc70 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2fc80 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
2fc90 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2fca0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
2fcb0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2fcc0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2fcd0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
2fce0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2fcf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2fd00 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2fd10 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
2fd20 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2fd30 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2fd40 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2fd50 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
2fd60 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
2fd70 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2fd80 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
2fd90 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
2fda0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
2fdb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fdc0 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
2fdd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
2fde0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
2fdf0 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
2fe00 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
2fe10 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
2fe20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
2fe30 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
2fe40 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
2fe50 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
2fe60 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2fe70 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
2fe80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2fe90 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2fea0 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
2feb0 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
2fec0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
2fed0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2fee0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
2fef0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
2ff00 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
2ff10 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
2ff20 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
2ff30 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2ff40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2ff50 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
2ff60 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
2ff70 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
2ff80 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2ff90 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
2ffa0 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
2ffb0 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
2ffc0 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
2ffd0 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
2ffe0 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
2fff0 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
30000 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
30010 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
30020 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
30030 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
30040 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
30050 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
30060 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
30070 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51  n_count()].*/.SQ
30080 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
30090 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
300a0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
300b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
300c0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
300d0 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
300e0 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
300f0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
30100 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
30110 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
30120 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
30130 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
30140 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
30150 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
30160 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
30170 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
30180 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
30190 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
301a0 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
301b0 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
301c0 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
301d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
301e0 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
301f0 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
30200 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
30210 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
30220 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
30230 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
30240 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
30250 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
30260 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
30270 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
30280 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
30290 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
302a0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
302b0 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
302c0 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
302d0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
302e0 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
302f0 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
30300 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
30310 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
30320 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
30330 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
30340 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
30350 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
30360 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
30370 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
30380 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
30390 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
303a0 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
303b0 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
303c0 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
303d0 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
303e0 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
303f0 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
30400 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
30410 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
30420 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
30430 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
30440 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
30450 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
30460 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
30470 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
30480 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
30490 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
304a0 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
304b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
304c0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
304d0 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
304e0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
304f0 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
30500 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
30510 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
30520 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
30530 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
30540 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
30550 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
30560 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
30570 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
30580 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
30590 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
305a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
305b0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
305c0 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
305d0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
305e0 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
305f0 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
30600 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
30610 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
30620 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
30630 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
30640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
30650 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
30660 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
30670 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
30680 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
30690 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
306a0 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
306b0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
306c0 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
306d0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
306e0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
306f0 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
30700 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
30710 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
30720 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
30730 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
30740 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
30750 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
30760 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
30770 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
30780 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
30790 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
307a0 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
307b0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
307c0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
307d0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
307e0 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
307f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30800 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
30810 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
30820 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
30830 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
30840 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
30850 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
30860 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
30870 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
30880 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
30890 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
308a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
308b0 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
308c0 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
308d0 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
308e0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
308f0 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
30900 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
30910 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
30920 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
30930 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
30940 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
30950 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
30960 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
30970 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
30980 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
30990 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
309a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
309b0 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
309c0 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
309d0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
309e0 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
309f0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
30a00 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
30a10 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
30a20 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
30a30 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
30a40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
30a50 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
30a60 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
30a70 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
30a80 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
30a90 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
30aa0 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
30ab0 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
30ac0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
30ad0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
30ae0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
30af0 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
30b00 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
30b10 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
30b20 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
30b30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30b40 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
30b50 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
30b60 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
30b70 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
30b80 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
30b90 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
30ba0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30bb0 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
30bc0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
30bd0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
30be0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
30bf0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
30c00 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
30c10 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
30c20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30c30 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
30c40 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
30c50 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
30c60 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
30c70 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
30c80 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
30c90 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
30ca0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
30cb0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
30cc0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
30cd0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
30ce0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
30cf0 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
30d00 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
30d10 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
30d20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
30d30 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
30d40 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
30d50 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
30d60 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
30d70 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
30d80 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
30d90 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
30da0 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
30db0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
30dc0 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
30dd0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
30de0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
30df0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
30e00 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
30e10 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
30e20 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
30e30 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
30e40 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
30e50 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
30e60 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
30e70 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
30e80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
30e90 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
30ea0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
30eb0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
30ec0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30ed0 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
30ee0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
30ef0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
30f00 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
30f10 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
30f20 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
30f30 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
30f40 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
30f50 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
30f60 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
30f70 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
30f80 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
30f90 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
30fa0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
30fb0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
30fc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
30fd0 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
30fe0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
30ff0 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
31000 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
31010 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
31020 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
31030 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
31040 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
31050 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
31060 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31070 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
31080 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
31090 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
310a0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
310b0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
310c0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
310d0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
310e0 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
310f0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
31100 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
31110 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
31120 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
31130 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
31140 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
31150 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
31160 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
31170 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
31180 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
31190 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
311a0 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
311b0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c  pointer..**.** <
311c0 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e  b>Warning:</b> ^
311d0 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
311e0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
311f0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
31200 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
31210 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
31220 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e  lue] object.  In
31230 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64   a multithreaded
31240 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a   environment,.**
31250 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
31260 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
31270 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ject may only be
31280 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74   used safely wit
31290 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  h.** [sqlite3_bi
312a0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
312b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
312c0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
312d0 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
312e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
312f0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
31300 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
31310 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
31320 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
31330 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
31340 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
31350 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
31360 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
31370 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
31380 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
31390 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
313a0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62  _bytes()], the b
313b0 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74  ehavior is not t
313c0 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a  hreadsafe..**.**
313d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
313e0 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
313f0 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
31400 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
31410 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
31420 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
31430 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
31440 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
31450 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
31460 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
31470 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
31480 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
31490 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
314a0 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
314b0 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
314c0 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
314d0 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
314e0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
314f0 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
31500 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
31510 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
31520 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
31530 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
31540 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
31550 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
31560 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
31570 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
31580 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
31590 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
315a0 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
315b0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
315c0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
315d0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
315e0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
315f0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
31600 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
31610 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
31620 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
31630 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
31640 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
31650 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
31660 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
31670 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
31680 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
31690 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
316a0 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
316b0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
316c0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
316d0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
316e0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
316f0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
31700 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
31710 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
31720 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
31730 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
31740 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
31750 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
31760 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
31770 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
31780 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
31790 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
317a0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
317b0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
317c0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
317d0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43   BLOB    <td> [C
317e0 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20  AST] to BLOB.** 
317f0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
31800 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
31810 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
31820 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
31830 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
31840 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
31850 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
31860 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
31870 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
31880 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
31890 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
318a0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
318b0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
318c0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
318d0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
318e0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
318f0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
31900 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
31910 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
31920 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
31930 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
31940 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
31950 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
31960 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
31970 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
31980 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
31990 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
319a0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
319b0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
319c0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
319d0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
319e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
319f0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
31a00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
31a10 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
31a20 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
31a30 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
31a40 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
31a50 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
31a60 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
31a70 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
31a80 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
31a90 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
31aa0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
31ab0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
31ac0 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
31ad0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31ae0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
31af0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
31b00 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
31b10 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
31b20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
31b30 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
31b40 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
31b50 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
31b60 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
31b70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
31b80 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
31b90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
31ba0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
31bb0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
31bc0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
31bd0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
31be0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
31bf0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
31c00 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
31c10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
31c20 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
31c30 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
31c40 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
31c50 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
31c60 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
31c70 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
31c80 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
31c90 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
31ca0 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
31cb0 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
31cc0 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
31cd0 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
31ce0 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
31cf0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
31d00 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
31d10 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
31d20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
31d30 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
31d40 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
31d50 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
31d60 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
31d70 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
31d80 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
31d90 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
31da0 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
31db0 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
31dc0 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
31dd0 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
31de0 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
31df0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
31e00 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
31e10 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
31e20 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  est policy is to
31e30 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
31e40 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
31e50 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
31e60 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
31e70 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
31e80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
31e90 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
31ea0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31eb0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
31ec0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
31ed0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
31ee0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
31ef0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
31f00 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
31f10 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
31f20 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
31f30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
31f40 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
31f50 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
31f60 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
31f70 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
31f80 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
31f90 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
31fa0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
31fb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
31fc0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
31fd0 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
31fe0 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
31ff0 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
32000 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
32010 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
32020 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
32030 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
32040 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
32050 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
32060 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
32070 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
32080 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
32090 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
320a0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
320b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
320c0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
320d0 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
320e0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
320f0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
32100 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
32110 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32120 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
32130 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
32140 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
32150 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
32160 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
32170 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
32180 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
32190 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
321a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
321b0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
321c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
321d0 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
321e0 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
321f0 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
32200 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
32210 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
32220 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f  ally.  Do <em>no
32230 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20  t</em> pass the 
32240 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
32250 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
32260 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
32270 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
32280 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
32290 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
322a0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
322b0 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
322c0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
322d0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
322e0 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
322f0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
32300 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
32310 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
32320 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
32330 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
32340 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
32350 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
32360 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
32370 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
32380 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
32390 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
323a0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
323b0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
323c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
323d0 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ].)^.*/.SQLITE_A
323e0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
323f0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
32400 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
32410 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
32420 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
32430 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
32440 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
32450 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
32460 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
32470 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
32480 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
32490 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
324a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
324b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
324c0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
324d0 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 45  PI double SQLITE
324e0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
324f0 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
32500 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
32510 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
32520 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
32530 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
32540 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
32550 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
32560 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
32570 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c  qlite3_int64 SQL
32580 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
32590 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
325a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
325b0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
325c0 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69  E_API const unsi
325d0 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c 49 54  gned char *SQLIT
325e0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
325f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
32600 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
32610 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
32620 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
32630 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
32640 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32650 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
32660 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
32670 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
32680 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
32690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
326a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
326b0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
326c0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c  _API sqlite3_val
326d0 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ue *SQLITE_STDCA
326e0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
326f0 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
32700 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
32710 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32720 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
32730 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
32740 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55  Object.** DESTRU
32750 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
32760 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
32770 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
32780 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
32790 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
327a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
327b0 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
327c0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
327d0 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
327e0 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
327f0 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
32800 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
32810 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
32820 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
32830 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
32840 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
32850 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
32860 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
32870 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
32880 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
32890 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
328a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
328b0 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
328c0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
328d0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
328e0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
328f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32900 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
32910 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
32920 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
32930 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
32940 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
32950 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32960 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
32970 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
32980 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
32990 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
329a0 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
329b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
329c0 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
329d0 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
329e0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
329f0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
32a00 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
32a10 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
32a20 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
32a30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
32a40 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
32a50 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
32a60 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
32a70 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
32a80 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
32a90 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
32aa0 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
32ab0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
32ac0 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
32ad0 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
32ae0 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
32af0 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
32b00 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
32b10 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
32b20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32b30 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
32b40 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
32b50 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
32b60 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
32b70 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
32b80 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
32b90 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
32ba0 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
32bb0 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
32bc0 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
32bd0 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
32be0 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  rruption..*/.SQL
32bf0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
32c00 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
32c10 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
32c20 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
32c30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32c40 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
32c50 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
32c60 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ject.** METHOD: 
32c70 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
32c80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
32c90 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
32ca0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
32cb0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
32cc0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
32cd0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
32ce0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
32cf0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
32d00 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
32d10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
32d20 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
32d30 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
32d40 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
32d50 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
32d60 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
32d70 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
32d80 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
32d90 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
32da0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
32db0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
32dc0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
32dd0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
32de0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
32df0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
32e00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32e10 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
32e20 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
32e30 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
32e40 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
32e50 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
32e60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
32e70 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
32e80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32e90 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
32ea0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
32eb0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
32ec0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
32ed0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
32ee0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
32ef0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
32f00 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
32f10 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
32f20 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
32f30 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
32f40 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
32f50 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
32f60 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
32f70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
32f80 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
32f90 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
32fa0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
32fb0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
32fc0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
32fd0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
32fe0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
32ff0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
33000 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
33010 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
33020 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
33030 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
33040 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
33050 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
33060 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
33070 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
33080 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
33090 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
330a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
330b0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
330c0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
330d0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
330e0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
330f0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
33100 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
33110 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33120 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
33130 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
33140 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33150 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
33160 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
33170 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
33180 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
33190 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
331a0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
331b0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
331c0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
331d0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
331e0 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
331f0 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
33200 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
33210 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
33220 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
33230 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
33240 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
33250 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
33260 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
33270 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
33280 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
33290 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
332a0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
332b0 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
332c0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
332d0 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
332e0 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
332f0 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
33300 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
33310 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
33320 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
33330 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
33340 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
33350 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
33360 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
33370 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
33380 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
33390 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
333a0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
333b0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
333c0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
333d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
333e0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
333f0 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
33400 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
33410 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
33420 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
33430 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
33440 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
33450 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
33460 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
33470 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
33480 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
33490 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
334a0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
334b0 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
334c0 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
334d0 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
334e0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
334f0 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
33500 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
33510 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
33520 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
33530 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
33540 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
33550 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
33560 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
33570 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
33580 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
33590 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
335a0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
335b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
335c0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
335d0 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
335e0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
335f0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
33600 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
33610 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
33620 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
33630 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
33640 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
33650 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
33660 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
33670 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
33680 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
33690 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
336a0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
336b0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
336c0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
336d0 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
336e0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
336f0 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
33700 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
33710 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
33720 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
33730 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
33740 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
33750 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
33760 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
33770 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
33780 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
33790 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
337a0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
337b0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
337c0 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  s.  The applicat
337d0 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74  ion should set t
337e0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  his parameter to
337f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
33800 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63  6LE] if the func
33810 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
33820 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20  ion invokes .** 
33830 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
33840 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e  ext16le()] on an
33850 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49   input, or [SQLI
33860 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74  TE_UTF16BE] if t
33870 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
33880 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71  tion invokes [sq
33890 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
338a0 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16be()] on an in
338b0 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  put, or.** [SQLI
338c0 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71  TE_UTF16] if [sq
338d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
338e0 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f  16()] is used, o
338f0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a  r [SQLITE_UTF8].
33900 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e  ** otherwise.  ^
33910 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  The same SQL fun
33920 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
33930 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
33940 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20   times using.** 
33950 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72  different prefer
33960 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
33970 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65  gs, with differe
33980 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
33990 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65  ns for.** each e
339a0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65  ncoding..** ^Whe
339b0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
339c0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
339d0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
339e0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
339f0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
33a00 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
33a10 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
33a20 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
33a30 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
33a40 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
33a50 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70  parameter may op
33a60 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64  tionally be ORed
33a70 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
33a80 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20  TERMINISTIC].** 
33a90 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74  to signal that t
33aa0 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  he function will
33ab0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
33ac0 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67  he same result g
33ad0 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  iven.** the same
33ae0 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61   inputs within a
33af0 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
33b00 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c  ement.  Most SQL
33b10 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a   functions are.*
33b20 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  * deterministic.
33b30 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b    The built-in [
33b40 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75  random()] SQL fu
33b50 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61  nction is an exa
33b60 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e  mple of a.** fun
33b70 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  ction that is no
33b80 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  t deterministic.
33b90 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65    The SQLite que
33ba0 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62  ry planner is ab
33bb0 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d  le to.** perform
33bc0 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69   additional opti
33bd0 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74  mizations on det
33be0 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74  erministic funct
33bf0 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20  ions, so use.** 
33c00 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44  of the [SQLITE_D
33c10 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c  ETERMINISTIC] fl
33c20 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ag is recommende
33c30 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65  d where possible
33c40 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
33c50 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
33c60 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
33c70 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
33c80 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
33c90 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
33ca0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
33cb0 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
33cc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
33cd0 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
33ce0 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
33cf0 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
33d00 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
33d10 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
33d20 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
33d30 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
33d40 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
33d50 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
33d60 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
33d70 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
33d80 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
33d90 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
33da0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
33db0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
33dc0 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
33dd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
33de0 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
33df0 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
33e00 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
33e10 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
33e20 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
33e30 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
33e40 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
33e50 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
33e60 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
33e70 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
33e80 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
33e90 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
33ea0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
33eb0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
33ec0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
33ed0 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
33ee0 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
33ef0 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
33f00 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
33f10 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
33f20 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33f30 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
33f40 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
33f50 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
33f60 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
33f70 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
33f80 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
33f90 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
33fa0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
33fb0 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
33fc0 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
33fd0 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
33fe0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
33ff0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
34000 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
34010 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
34020 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
34030 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
34040 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34050 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
34060 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
34070 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
34080 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
34090 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
340a0 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
340b0 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
340c0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
340d0 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
340e0 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
340f0 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
34100 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
34110 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
34120 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
34130 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
34140 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
34150 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
34160 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
34170 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
34180 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
34190 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
341a0 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
341b0 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
341c0 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
341d0 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
341e0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
341f0 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
34200 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
34210 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34220 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
34230 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
34240 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
34250 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
34260 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
34270 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
34280 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
34290 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
342a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
342b0 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
342c0 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
342d0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
342e0 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
342f0 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
34300 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
34310 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
34320 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
34330 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
34340 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
34350 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
34360 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
34370 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
34380 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
34390 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
343a0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
343b0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
343c0 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
343d0 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
343e0 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
343f0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
34400 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
34410 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
34420 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
34430 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
34440 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
34450 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
34460 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
34470 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34480 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
34490 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
344a0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
344b0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
344c0 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
344d0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
344e0 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
344f0 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
34500 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
34510 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34520 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
34530 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
34540 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
34550 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
34560 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
34570 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
34580 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
34590 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65  CALL sqlite3_cre
345a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
345b0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
345c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
345d0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
345e0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
345f0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
34600 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
34610 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
34620 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
34630 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
34640 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
34650 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
34660 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
34670 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
34680 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
34690 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
346a0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
346b0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72  DCALL sqlite3_cr
346c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
346d0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
346e0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
346f0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
34700 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
34710 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
34720 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
34730 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
34740 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
34750 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
34760 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
34770 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
34780 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
34790 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
347a0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
347b0 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54  ntext*).);.SQLIT
347c0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
347d0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
347e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
347f0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
34800 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
34810 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
34820 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
34830 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
34840 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
34850 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
34860 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
34870 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
34880 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
34890 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
348a0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
348b0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
348c0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
348d0 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
348e0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
348f0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
34900 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
34910 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
34920 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
34930 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
34940 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
34950 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
34960 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
34970 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
34980 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
34990 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
349a0 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d        1    /* IM
349b0 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36  P: R-37514-35566
349c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
349d0 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
349e0 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    2    /* IMP: R
349f0 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a  -03371-37637 */.
34a00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
34a10 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20  TF16BE        3 
34a20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39     /* IMP: R-519
34a30 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66  71-34154 */.#def
34a40 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
34a50 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
34a60 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
34a70 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
34a80 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
34a90 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
34aa0 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23   Deprecated */.#
34ab0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
34ac0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
34ad0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
34ae0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
34af0 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
34b00 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
34b10 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Flags.**.** Thes
34b20 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  e constants may 
34b30 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72  be ORed together
34b40 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
34b50 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65  QLITE_UTF8 | pre
34b60 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
34b70 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75  ding] as the fou
34b80 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rth argument.** 
34b90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
34ba0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
34bb0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
34bc0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  function16()], o
34bd0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
34be0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
34bf0 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
34c00 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
34c10 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f  STIC    0x800../
34c20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
34c30 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
34c40 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
34c50 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
34c60 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
34c70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
34c80 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
34c90 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
34ca0 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
34cb0 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
34cc0 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
34cd0 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
34ce0 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
34cf0 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
34d00 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
34d10 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
34d20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
34d30 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70    To encourage p
34d40 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76  rogrammers to av
34d50 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e  oid.** these fun
34d60 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20  ctions, we will 
34d70 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74  not explain what
34d80 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
34d90 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
34da0 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
34db0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
34dc0 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c  PRECATED int SQL
34dd0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
34de0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
34df0 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
34e00 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
34e10 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
34e20 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  TED int SQLITE_S
34e30 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
34e40 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
34e50 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
34e60 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
34e70 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  TED int SQLITE_S
34e80 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74  TDCALL sqlite3_t
34e90 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
34ea0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
34eb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
34ec0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
34ed0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
34ee0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
34ef0 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
34f00 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
34f10 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
34f20 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
34f30 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
34f40 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
34f50 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
34f60 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
34f70 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51  EPRECATED int SQ
34f80 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
34f90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
34fa0 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
34fb0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
34fc0 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  t),.            
34fd0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c            void*,
34fe0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
34ff0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
35000 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
35010 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20  g SQL Values.** 
35020 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
35030 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  value.**.** The 
35040 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
35050 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
35060 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
35070 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
35080 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
35090 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
350a0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
350b0 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
350c0 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
350d0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
350e0 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75    .**.** The xFu
350f0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
35100 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
35110 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
35120 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
35130 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
35140 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
35150 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
35160 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
35170 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
35180 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
35190 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
351a0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
351b0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
351c0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
351d0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
351e0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
351f0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
35200 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
35210 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
35220 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
35230 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
35240 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
35250 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
35260 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
35270 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
35280 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
35290 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
352a0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
352b0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
352c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
352d0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
352e0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
352f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
35300 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
35310 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
35320 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
35330 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
35340 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
35350 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
35360 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
35370 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
35380 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
35390 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
353a0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
353b0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
353c0 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
353d0 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72 6f  pt that these ro
353e0 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
353f0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
35400 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
35410 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
35420 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
35430 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
35440 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
35450 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
35460 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
35470 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
35480 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
35490 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
354a0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
354b0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
354c0 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
354d0 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
354e0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
354f0 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
35500 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
35510 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
35520 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
35530 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
35540 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
35550 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
35560 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
35570 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
35580 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
35590 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
355a0 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
355b0 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
355c0 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
355d0 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
355e0 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
355f0 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
35600 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
35610 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
35620 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
35630 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
35640 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
35650 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
35660 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
35670 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
35680 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
35690 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
356a0 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
356b0 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
356c0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
356d0 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
356e0 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
356f0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
35700 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
35710 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
35720 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
35730 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
35740 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
35750 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
35760 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
35770 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
35780 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
35790 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
357a0 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
357b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
357c0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
357d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
357e0 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
357f0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
35800 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
35810 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
35820 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
35830 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
35840 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
35850 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
35860 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
35870 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
35880 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
35890 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
358a0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
358b0 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
358c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
358d0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
358e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
358f0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
35900 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
35910 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
35920 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
35930 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
35940 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
35950 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
35960 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
35970 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
35980 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
35990 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
359a0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
359b0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
359c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
359d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
359e0 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ble SQLITE_STDCA
359f0 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
35a00 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
35a10 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
35a20 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
35a30 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
35a40 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
35a50 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
35a60 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
35a70 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  64 SQLITE_STDCAL
35a80 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
35a90 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
35aa0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
35ab0 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  I const unsigned
35ac0 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
35ad0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
35ae0 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
35af0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
35b00 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
35b10 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
35b20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
35b30 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
35b40 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
35b50 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
35b60 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
35b70 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
35b80 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
35b90 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
35ba0 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
35bb0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
35bc0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
35bd0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
35be0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
35bf0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
35c00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
35c10 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
35c20 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
35c30 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
35c40 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
35c50 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
35c60 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
35c70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
35c80 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74 79  inding The Subty
35c90 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73  pe Of SQL Values
35ca0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
35cb0 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
35cc0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
35cd0 65 5f 73 75 62 74 79 70 65 28 56 29 20 66 75 6e  e_subtype(V) fun
35ce0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
35cf0 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a  e subtype for.**
35d00 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   an [application
35d10 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
35d20 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20  ction] argument 
35d30 56 2e 20 20 54 68 65 20 73 75 62 74 79 70 65 0a  V.  The subtype.
35d40 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63  ** information c
35d50 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70 61  an be used to pa
35d60 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f  ss a limited amo
35d70 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66  unt of context f
35d80 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66  rom.** one SQL f
35d90 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68  unction to anoth
35da0 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71  er.  Use the [sq
35db0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62  lite3_result_sub
35dc0 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  type()].** routi
35dd0 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20 73 75  ne to set the su
35de0 62 74 79 70 65 20 66 6f 72 20 74 68 65 20 72 65  btype for the re
35df0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e  turn value of an
35e00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
35e10 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  *.** SQLite make
35e20 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74  s no use of subt
35e30 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20  ype itself.  It 
35e40 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20 74 68  merely passes th
35e50 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f  e subtype.** fro
35e60 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  m the result of 
35e70 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  one [application
35e80 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
35e90 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a  ction] into the.
35ea0 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74  ** input of anot
35eb0 68 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  her..*/.SQLITE_A
35ec0 50 49 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20  PI unsigned int 
35ed0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
35ee0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62  qlite3_value_sub
35ef0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
35f00 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
35f10 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20  I3REF: Copy And 
35f20 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a  Free SQL Values.
35f30 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
35f40 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e  e3_value.**.** ^
35f50 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
35f60 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61  e_dup(V) interfa
35f70 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
35f80 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
35f90 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
35fa0 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61   D and returns a
35fb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
35fc0 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71   copy.  ^The [sq
35fd0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74  lite3_value] ret
35fe0 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70  urned.** is a [p
35ff0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
36000 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65  _value] object e
36010 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74  ven if the input
36020 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65   is not..** ^The
36030 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
36040 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20  up(V) interface 
36050 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
36060 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20  V is NULL or if 
36070 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
36080 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a  cation fails..**
36090 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
360a0 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69  _value_free(V) i
360b0 6e 74 65 72 66 61 63 65 20 66 72 65 65 73 20 61  nterface frees a
360c0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  n [sqlite3_value
360d0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76  ] object.** prev
360e0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
360f0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
36100 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66  lue_dup()].  ^If
36110 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   V is a NULL poi
36120 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  nter.** then sql
36130 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28  ite3_value_free(
36140 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  V) is a harmless
36150 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54   no-op..*/.SQLIT
36160 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61  E_API sqlite3_va
36170 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  lue *SQLITE_STDC
36180 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
36190 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69  e_dup(const sqli
361a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
361b0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
361c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
361d0 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 73  te3_value_free(s
361e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
361f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36200 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
36210 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
36220 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  xt.** METHOD: sq
36230 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
36240 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
36250 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
36260 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
36270 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
36280 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
36290 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
362a0 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
362b0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
362c0 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
362d0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
362e0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
362f0 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
36300 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
36310 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
36320 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
36330 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
36340 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
36350 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
36360 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
36370 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
36380 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
36390 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
363a0 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
363b0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
363c0 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
363d0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
363e0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
363f0 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
36400 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
36410 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
36420 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
36430 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
36440 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
36450 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
36460 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
36470 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
36480 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
36490 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
364a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
364b0 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
364c0 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
364d0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
364e0 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
364f0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
36500 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
36510 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
36520 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
36530 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
36540 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
36550 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
36560 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
36570 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
36580 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
36590 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
365a0 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
365b0 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
365c0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
365d0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
365e0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
365f0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
36600 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a   NULL pointer .*
36610 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c  * when first cal
36620 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73  led if N is less
36630 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
36640 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
36650 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
36660 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
36670 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
36680 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
36690 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
366a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
366b0 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
366c0 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
366d0 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
366e0 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
366f0 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
36700 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
36710 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
36720 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
36730 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
36740 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
36750 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
36760 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
36770 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
36780 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
36790 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20   allocation.)^  
367a0 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61  Within the xFina
367b0 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69  l callback, it i
367c0 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73  s customary to s
367d0 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c  et.** N=0 in cal
367e0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
367f0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
36800 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20  C,N) so that no 
36810 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65  .** pointless me
36820 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
36830 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53   occur..**.** ^S
36840 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
36850 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
36860 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
36870 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
36880 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
36890 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
368a0 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
368b0 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
368c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
368d0 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
368e0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
368f0 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
36900 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
36910 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
36920 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
36930 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
36940 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
36950 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
36960 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
36970 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
36980 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
36990 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
369a0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
369b0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
369c0 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
369d0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
369e0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
369f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
36a00 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
36a10 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
36a20 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
36a30 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
36a40 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
36a50 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
36a60 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
36a70 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
36a80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
36a90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36aa0 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
36ab0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
36ac0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
36ad0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
36ae0 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
36af0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
36b00 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
36b10 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
36b20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
36b30 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
36b40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36b50 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
36b60 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
36b70 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
36b80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
36b90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
36ba0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
36bb0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
36bc0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
36bd0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
36be0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
36bf0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
36c00 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
36c10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
36c20 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
36c30 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 73 65 72  ALL sqlite3_user
36c40 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
36c50 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
36c60 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
36c70 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
36c80 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  r Functions.** M
36c90 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
36ca0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  ontext.**.** ^Th
36cb0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
36cc0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
36cd0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
36ce0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
36cf0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
36d00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36d10 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
36d20 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
36d30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
36d40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
36d50 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
36d60 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
36d70 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
36d80 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
36d90 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
36da0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
36db0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
36dc0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
36dd0 74 65 33 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  te3 *SQLITE_STDC
36de0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ALL sqlite3_cont
36df0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
36e00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
36e10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36e20 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
36e30 69 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54  iary Data.** MET
36e40 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
36e50 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  text.**.** These
36e60 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
36e70 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61  e used by (non-a
36e80 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75  ggregate) SQL fu
36e90 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
36ea0 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
36eb0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
36ec0 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
36ed0 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
36ee0 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
36ef0 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
36f00 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
36f10 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
36f20 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
36f30 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
36f40 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
36f50 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
36f60 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
36f70 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ved.  An example
36f80 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69  .** of where thi
36f90 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75  s might be usefu
36fa0 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61  l is in a regula
36fb0 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
36fc0 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  ching.** functio
36fd0 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
36fe0 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
36ff0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
37000 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  n can be stored 
37010 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
37020 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
37030 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
37040 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20  g.  .** Then as 
37050 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74  long as the patt
37060 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69  ern string remai
37070 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20  ns the same,.** 
37080 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  the compiled reg
37090 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
370a0 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
370b0 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
370c0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
370d0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  same function..*
370e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
370f0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
37100 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
37110 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
37120 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  he metadata.** a
37130 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
37140 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
37150 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
37160 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
37170 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
37180 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
37190 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
371a0 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73  on. ^If there is
371b0 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20   no metadata.** 
371c0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
371d0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  the function arg
371e0 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69  ument, this sqli
371f0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
37200 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
37210 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
37220 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
37230 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
37240 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69  xdata(C,N,P,X) i
37250 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50  nterface saves P
37260 20 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72   as metadata for
37270 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
37280 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
37290 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
372a0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62   function.  ^Sub
372b0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
372c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
372d0 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74  auxdata(C,N) ret
372e0 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d  urn P from the m
372f0 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71  ost recent.** sq
37300 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
37310 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20  a(C,N,P,X) call 
37320 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  if the metadata 
37330 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f  is still valid o
37340 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65  r.** NULL if the
37350 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
37360 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  en discarded..**
37370 20 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c   ^After each cal
37380 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
37390 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
373a0 29 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74  ) where X is not
373b0 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65   NULL,.** SQLite
373c0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
373d0 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
373e0 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61  tion X with para
373f0 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a  meter P exactly.
37400 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68  ** once, when th
37410 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69  e metadata is di
37420 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69  scarded..** SQLi
37430 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69  te is free to di
37440 73 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61  scard the metada
37450 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20  ta at any time, 
37460 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a  including: <ul>.
37470 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65  ** <li> when the
37480 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
37490 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
374a0 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a  r changes, or.**
374b0 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69   <li> when [sqli
374c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
374d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
374e0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66  e()] is called f
374f0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53  or the.**      S
37500 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72  QL statement, or
37510 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71  .** <li> when sq
37520 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
37530 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  a() is invoked a
37540 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65  gain on the same
37550 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a   parameter, or.*
37560 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68  * <li> during th
37570 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74  e original sqlit
37580 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
37590 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d   call when a mem
375a0 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c  ory .**      all
375b0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
375c0 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  curs. </ul>)^.**
375d0 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73  .** Note the las
375e0 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74  t bullet in part
375f0 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73  icular.  The des
37600 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a  tructor X in .**
37610 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
37620 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69  data(C,N,P,X) mi
37630 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d  ght be called im
37640 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
37650 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  e the.** sqlite3
37660 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
37670 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20 72 65  nterface even re
37680 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71  turns.  Hence sq
37690 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
376a0 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  a().** should be
376b0 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65   called near the
376c0 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63   end of the func
376d0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
376e0 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ion and the.** f
376f0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
37700 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f  tation should no
37710 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f  t make any use o
37720 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c  f P after.** sql
37730 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
37740 28 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  () has been call
37750 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70  ed..**.** ^(In p
37760 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
37770 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
37780 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
37790 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e  calls for.** fun
377a0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73  ction parameters
377b0 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c   that are compil
377c0 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73  e-time constants
377d0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65  , including lite
377e0 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
377f0 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61  d [parameters] a
37800 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63  nd expressions c
37810 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65  omposed from the
37820 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54   same.)^.**.** T
37830 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
37840 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
37850 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
37860 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
37870 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
37880 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
37890 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53  LITE_API void *S
378a0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
378b0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
378c0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
378d0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49  t*, int N);.SQLI
378e0 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49  TE_API void SQLI
378f0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
37900 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
37910 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37920 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
37930 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
37940 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
37950 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
37960 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
37970 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
37980 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  r.**.** These ar
37990 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73  e special values
379a0 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
379b0 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
379c0 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
379d0 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
379e0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
379f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
37a00 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68  blob()].  ^If th
37a10 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
37a20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49  argument is SQLI
37a30 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65  TE_STATIC, it me
37a40 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
37a50 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20  tent pointer is 
37a60 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20  constant.** and 
37a70 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67  will never chang
37a80 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20  e.  It does not 
37a90 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72  need to be destr
37aa0 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53  oyed.  ^The.** S
37ab0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
37ac0 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
37ad0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
37ae0 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
37af0 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
37b00 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
37b10 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
37b20 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
37b30 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
37b40 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
37b50 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
37b60 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
37b70 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
37b80 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
37b90 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
37ba0 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a  C++ compilers..*
37bb0 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
37bc0 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
37bd0 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
37be0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
37bf0 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
37c00 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
37c10 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
37c20 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
37c30 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
37c40 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
37c50 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
37c60 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
37c70 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
37c80 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54   Function.** MET
37c90 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
37ca0 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  text.**.** These
37cb0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
37cc0 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
37cd0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
37ce0 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
37cf0 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
37d00 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
37d10 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
37d20 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
37d30 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
37d40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
37d50 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
37d60 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
37d70 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
37d80 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
37d90 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
37da0 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
37db0 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
37dc0 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
37dd0 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
37de0 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
37df0 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
37e00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
37e10 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
37e20 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
37e30 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
37e40 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
37e50 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
37e60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
37e70 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
37e80 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
37e90 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
37ea0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
37eb0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
37ec0 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
37ed0 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
37ee0 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
37ef0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
37f00 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
37f10 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
37f20 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
37f30 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
37f40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37f50 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
37f60 6c 6f 62 28 43 2c 4e 29 20 61 6e 64 20 73 71 6c  lob(C,N) and sql
37f70 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
37f80 62 6c 6f 62 36 34 28 43 2c 4e 29 0a 2a 2a 20 69  blob64(C,N).** i
37f90 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
37fa0 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
37fb0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37fc0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
37fd0 62 65 0a 2a 2a 20 61 20 42 4c 4f 42 20 63 6f 6e  be.** a BLOB con
37fe0 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
37ff0 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
38000 65 73 20 69 6e 20 73 69 7a 65 2e 0a 2a 2a 0a 2a  es in size..**.*
38010 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
38020 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
38030 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
38040 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
38050 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
38060 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
38070 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
38080 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
38090 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
380a0 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
380b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
380c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
380d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
380e0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
380f0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
38100 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
38110 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
38120 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
38130 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  tion..** ^SQLite
38140 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67   uses the string
38150 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
38160 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65  he.** 2nd parame
38170 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72  ter of sqlite3_r
38180 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
38190 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
381a0 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20  error16().** as 
381b0 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65  the text of an e
381c0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e  rror message.  ^
381d0 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
381e0 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
381f0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72  essage string fr
38200 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
38210 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46  t_error() as UTF
38220 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69  -8. ^SQLite.** i
38230 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
38240 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
38250 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
38260 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  () as UTF-16 in 
38270 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
38280 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74  rder.  ^If the t
38290 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
382a0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
382b0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
382c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
382d0 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74  ror16() is negat
382e0 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
382f0 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72  takes as the err
38300 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c  or.** message al
38310 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67  l text up throug
38320 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
38330 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
38340 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
38350 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
38360 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
38370 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
38380 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
38390 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20  is non-negative 
383a0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
383b0 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62  s that many.** b
383c0 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
383d0 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32  ters) from the 2
383e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  nd parameter as 
383f0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
38400 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  e..** ^The sqlit
38410 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
38420 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
38430 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
38440 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20  * routines make 
38450 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  a private copy o
38460 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  f the error mess
38470 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a  age text before.
38480 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20  ** they return. 
38490 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c   Hence, the call
384a0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  ing function can
384b0 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a   deallocate or.*
384c0 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78  * modify the tex
384d0 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74  t after they ret
384e0 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d  urn without harm
384f0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
38500 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
38510 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
38520 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
38530 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
38540 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
38550 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
38560 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
38570 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c  n.  ^By default,
38580 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f  .** the error co
38590 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52  de is SQLITE_ERR
385a0 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65  OR.  ^A subseque
385b0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
385c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
385d0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
385e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
385f0 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f   resets the erro
38600 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45  r code to SQLITE
38610 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _ERROR..**.** ^T
38620 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
38630 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29  t_error_toobig()
38640 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
38650 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
38660 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e  w an.** error in
38670 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
38680 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
38690 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65  s too long to re
386a0 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  present..**.** ^
386b0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
386c0 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29  lt_error_nomem()
386d0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
386e0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
386f0 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e  w an.** error in
38700 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
38710 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
38720 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
38730 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
38740 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
38750 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
38760 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
38770 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
38780 64 65 66 69 6e 65 64 20 66 75